Have you ever spent hours wrestling with dependency conflicts or tangled setup.py files? I have. After one too many afternoons lost to version mismatches and mysterious import errors, I decided there had to be a better way. That’s when I found Poetry, and it completely changed how I build and share Python code. This guide will show you how to do the same. Let’s build a professional package, together.
Think of a typical Python project. You have a requirements.txt file, a setup.py, maybe a MANIFEST.in. Keeping them all in sync is a chore. One tool simplifies everything: Poetry. It manages your project’s dependencies, virtual environment, building, and publishing from a single, clear file. Why use multiple tools when one can do it all?
Getting started is straightforward. You install Poetry and use it to create your project’s skeleton. This step builds the foundation. I prefer to keep my virtual environments inside the project folder. It keeps things tidy.
curl -sSL https://install.python-poetry.org | python3 -
poetry new my_awesome_package --src
cd my_awesome_package
poetry config virtualenvs.in-project trueThe command above creates a standard project layout. The most important file is pyproject.toml. This is your project’s command center. Here, you define everything: the package name, version, what Python versions you support, and all dependencies.
[tool.poetry]
name = "my_awesome_package"
version = "0.1.0"
description = "A clean, well-packaged Python library."
[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.31.0"
[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"
black = "^23.0.0"See how clean that is? Dependencies for users are listed under [tool.poetry.dependencies]. Tools only developers need, like pytest for testing, go in a separate [tool.poetry.group.dev.dependencies] section. This separation is crucial. It means when someone installs your package, they don’t get your linters and testing frameworks. Poetry handles this split perfectly.
Now, let’s talk about writing the actual code. A good structure makes your package easier to use and maintain. I use the src layout, where the package lives in a src/ directory. This avoids subtle import issues.
my_awesome_package/
├── src/
│ └── my_awesome_package/
│ ├── __init__.py
│ └── core.py
├── tests/
│ └── test_core.py
├── pyproject.toml
└── README.mdWhat does a simple module look like? Let’s write one. The key is clarity and good documentation.
# src/my_awesome_package/core.py
"""Core functionality for the package."""
def greet_user(name: str) -> str:
"""
Return a friendly greeting.
Args:
name: The name of the person to greet.
Returns:
A greeting string.
Example:
>>> greet_user("Alice")
'Hello, Alice!'
"""
return f"Hello, {name}!"Your __init__.py file controls what gets exported. This is your package’s public face.
# src/my_awesome_package/__init__.py
from .core import greet_user
__version__ = "0.1.0"
__all__ = ["greet_user"]With code written, how do you know it works? You test it. Poetry makes running tests simple.
poetry add --group dev pytest
poetry run pytestHere’s a corresponding test. Notice I’m using poetry run to execute commands inside the project’s virtual environment. This guarantees consistency.
# tests/test_core.py
from my_awesome_package import greet_user
def test_greet_user():
"""Test that the greeting is formatted correctly."""
result = greet_user("World")
assert result == "Hello, World!"But testing is just one part of code quality. Before you even commit code, you can run automatic checks. This is where pre-commit hooks shine. They catch style issues and simple bugs before they become problems. Have you ever fixed a typo in a variable name five commits later? Pre-commit hooks prevent that.
First, add the tool.
poetry add --group dev pre-commitThen, create a .pre-commit-config.yaml file in your project root.
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.4.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- repo: https://github.com/psf/black
rev: 23.1.0
hooks:
- id: blackInstall the hooks with poetry run pre-commit install. Now, every time you run git commit, Black will format your code and other hooks will check for common issues. It’s like having a meticulous assistant looking over your shoulder.
Let’s fast forward. Your code is written, tested, and styled. Now you want to share it with the world. This means building a distributable package and publishing it to PyPI. Poetry turns a complex, multi-step process into two commands.
First, build the package. This creates .tar.gz and .whl files in a dist/ folder.
poetry buildBefore you publish, have you configured your PyPI credentials? You only need to do this once. Poetry can store your token securely.
poetry config pypi-token.pypi YOUR_API_TOKEN_HEREFinally, publish. With one command, your package is live for anyone to install via pip.
poetry publishBut doing this manually for every release is tedious and error-prone. The real magic happens when you automate it. You can set up a GitHub Actions workflow that runs your tests on every push and publishes to PyPI when you tag a new version. This is the hallmark of a professional, maintainable project.
Create a file .github/workflows/test-and-publish.yml.
name: Test and Publish
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
release:
types: [published]
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.8", "3.9", "3.10", "3.11"]
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: ${{ matrix.python-version }}
- run: pip install poetry
- run: poetry install
- run: poetry run pytest
publish:
needs: test
if: github.event_name == 'release' && github.event.action == 'published'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-python@v4
with:
python-version: "3.10"
- run: pip install poetry
- run: poetry build
- run: poetry publish
env:
POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}This workflow does two jobs. First, the test job runs your test suite across multiple Python versions on every push. This ensures compatibility. The publish job only triggers when you create a new GitHub Release. It builds the package and publishes it using a secure token stored in your repository secrets. Once set up, releasing a new version is as simple as creating a tag.
Building a Python package this way might seem like a lot of upfront work. I thought so too. But the time you save on debugging dependency hell and manual releases is immense. It gives you confidence. You can focus on writing great code, not on managing the machinery around it.
The journey from a script on your laptop to a package used by others is incredibly rewarding. By using tools like Poetry, you’re not just making your own life easier; you’re making life easier for everyone who uses your code. You’re building something robust, reliable, and ready for the real world.
I hope this guide helps you package your next great idea. What will you build? If you found this useful, please share it with a friend or colleague who’s struggling with Python packaging. Have questions or your own tips? Leave a comment below—I’d love to hear about your experiences.
As a best-selling author, I invite you to explore my books on Amazon. Don’t forget to follow me on Medium and show your support. Thank you! Your support means the world!
101 Books
101 Books is an AI-driven publishing company co-founded by author Aarav Joshi. By leveraging advanced AI technology, we keep our publishing costs incredibly low—some books are priced as low as $4—making quality knowledge accessible to everyone.
Check out our book Golang Clean Code available on Amazon.
Stay tuned for updates and exciting news. When shopping for books, search for Aarav Joshi to find more of our titles. Use the provided link to enjoy special discounts!
📘 Checkout my latest ebook for free on my channel!
Be sure to like, share, comment, and subscribe to the channel!
Our Creations
Be sure to check out our creations:
Investor Central | Investor Central Spanish | Investor Central German | Smart Living | Epochs & Echoes | Puzzling Mysteries | Hindutva | Elite Dev | JS Schools
We are on Medium
Tech Koala Insights | Epochs & Echoes World | Investor Central Medium | Puzzling Mysteries Medium | Science & Epochs Medium | Modern Hindutva
