Project Delivery

Guide to Creating and Distributing Python Packages via Version Control using Poetry

Feeling overwhelmed by Python package management and distribution? This guide empowers you to take control! Leverage version control and Poetry to streamline your development workflow. Master best practices for building, distributing, and publishing your packages, ensuring efficient collaboration and effortless delivery.

Franco Passeggi
February 27, 2024

Introduction

This guide serves Python developers who wish to refine their package management and distribution practices using version control. The primary intention is to streamline the process of package creation, management, and distribution, ensuring efficiency and consistency across development cycles. Developers often face obstacles such as managing dependencies, versioning, and ensuring package integrity across environments. By leveraging version control systems and tools like Poetry, these challenges can be mitigated.

The guide outlines steps to set up a project, manage dependencies, and automate package distribution, effectively overcoming common hurdles. By following the practices detailed below, developers can achieve package distribution, enhance collaboration, and maintain high-quality software delivery.

Creating Your Package

1. Initial Repository Setup

  • Create a New Repository: Begin by initializing a new repository for your Python package:

2. Local Development Environment

  • Setting Up Your Local Directory:

     This step creates a dedicated directory for your package and moves you into it.

  • Initialize Your Project with Poetry:

     Poetry is a tool used for Python dependency management and packaging.

3. .gitignore Configuration

  • Setting Up .gitignore: A properly configured `.gitignore` file is crucial for Python projects. Here’s an example that you can use as a starting point:

4. Structuring Your Source Code

  • Create the Source Directory:

Your project structure should now include the `src` directory, along with other initial files created by poetry like `README.md`, `poetry.lock`, and `pyproject.toml`.

This is the default structure for Poetry – which is a clean structure and conforms with PEP 423.

5. Package Configuration with Poetry

  • Edit pyproject.toml: Specify which modules to include in your package by updating your `pyproject.toml` file:
  • Ensure Compatibility Across Python Versions: Your `pyproject.toml` should also specify the Python versions your package supports:

6. Development, Testing, and Building

     Run this command within the src directory. to test building your package.

During package development, the build process compiles and packages your code into distributable formats. When you run poetry build, Poetry compiles source files, incorporates dependencies specified in pyproject.toml, and generates a wheel and/or source archive. This ensures the package is isolated from local environments, making it reproducible across different systems. Testing the build verifies that the package can be installed and functions as expected in a clean environment.

7. Distributing Your Package

  • Push and Tag Your Changes:Once your changes are ready, push them to the repository and create a version tag.
  • Package Installation:

This command allows users to install your package.


If your repository is private, users will need proper credentials to access and install the package. For package installation from a private GitHub repository, the command slightly alters to include authentication details:

Here, <token> should be replaced with a personal access token (PAT) that grants read access to the repository. This method securely allows Poetry to clone the repository and install the package. Users with read credentials can seamlessly install the package using their access tokens, ensuring both distribution control and privacy.

8. Publishing to PyPI for Widespread Public Consumption

To make your package available to a broader audience via the Python Package Index (PyPI), follow these steps:

  • Prepare Your Package: Ensure your pyproject.toml includes all necessary information: project name, version, author, and other metadata. Verify your package is properly structured and all dependencies are correctly listed.
  • Create Accounts: If you haven't already, create accounts on PyPI and TestPyPI, a separate instance of the package index for testing and experimentation.
  • Build Your Package: Run poetry build to generate the distribution archives. This command produces a .tar.gz file and possibly wheel files in the dist directory.
  • Test Your Package: (Optional) Before publishing to PyPI, you might want to upload your package to TestPyPI to ensure it installs and works correctly. Use poetry publish --repository testpypi -u <username> -p <password> to upload it.
  • Publish to PyPI: Once you're ready to publish, use the command poetry publish -u <username> -p <password>. This command uploads your package to PyPI, making it available for anyone to install via pip install <package-name>.

Remember to update your package version in pyproject.toml for subsequent releases. Always test your package thoroughly to maintain quality and reliability for end users.

Conclusion

This guide aims to equip Python developers with the necessary knowledge and tools to manage and distribute Python packages effectively using version control. From initial setup to leveraging Poetry for dependency management and package configuration, the guide outlines a comprehensive approach to streamline the development process. Addressing common obstacles such as dependency management, version control, and package distribution, it provides practical solutions and best practices. The guide also extends into advanced topics like distributing private packages and publishing to PyPI for broader public consumption, ensuring developers have the resources to manage both private and public packages efficiently. By adhering to the practices outlined, developers can achieve streamlined package distribution, enhance collaboration among team members, and ensure consistent, high-quality software delivery across various environments.

We are Azumo
and we get it

We understand the struggle of finding the right software development team to build your service or solution.

Since our founding in 2016 we have heard countless horror stories of the vanishing developer, the never-ending late night conference calls with the offshore dev team, and the mounting frustration of dealing with buggy code, missed deadlines and poor communication. We built Azumo to solve those problems and offer you more. We deliver well trained, senior developers, excited to work, communicate and build software together that will advance your business.

Want to see how we can deliver for you?

schedule my call

Benefits You Can Expect

Release software features faster and maintain apps with Azumo. Our developers are not freelancers and we are not a marketplace. We take pride in our work and seat dedicated Azumo engineers with you who take ownership of the project and create valuable solutions for you.

Industry Experts

Businesses across industries trust Azumo. Our expertise spans industries from healthcare, finance, retail, e-commerce, media, education, manufacturing and more.

Illustration of globe for technology nearshore software development outsourcing

Real-Time Collaboration

Enjoy seamless collaboration with our time zone-aligned developers. Collaborate, brainstorm, and share feedback easily during your working hours.

vCTO Solution Illustration

Boost Velocity

Increase your development speed. Scale your team up or down as you need with confidence, so you can meet deadlines and market demand without compromise.

Illustration of bullseye for technology nearshore software development outsourcing

Agile Approach

We adhere to strict project management principles that guarantee outstanding software development results.

Quality Code

Benefits from our commitment to quality. Our developers receive continuous training, so they can deliver top-notch code.

Flexible Models

Our engagement models allow you to tailor our services to your budget, so you get the most value for your investment.

Client Testimonials

Zynga

Azumo has been great to work with. Their team has impressed us with their professionalism and capacity. We have a mature and sophisticated tech stack, and they were able to jump in and rapidly make valuable contributions.

Zynga
Drew Heidgerken
Director of Engineering
Zaplabs

We worked with Azumo to help us staff up our custom software platform redevelopment efforts and they delivered everything we needed.

Zaplabs
James Wilson
President
Discovery Channel

The work was highly complicated and required a lot of planning, engineering, and customization. Their development knowledge is impressive.

Discovery Channel
Costa Constantinou
Senior Product Manager
Twitter

Azumo helped my team with the rapid development of a standalone app at Twitter and were incredibly thorough and detail oriented, resulting in a very solid product.

Twitter
Seth Harris
Senior Program Manager
Wine Enthusiast

Azumo's staff augmentation service has greatly expanded our digital custom publishing capabilities. Projects as diverse as Skills for Amazon Alexa to database-driven mobile apps are handled quickly, professionally and error free.

Wine Enthusiast Magazine
Greg Remillard
Executive Director
Zemax

So much of a successful Cloud development project is the listening. The Azumo team listens. They clearly understood the request and quickly provided solid answers.

Zemax
Matt Sutton
Head of Product

How it Works

schedule my call

Step 1: Schedule your call

Find a time convenient for you to discuss your needs and goals

Step 2: We review the details

We estimate the effort, design the team, and propose a solution for you to collaborate.

Step 3: Design, Build, Launch, Maintain

Seamlessly partner with us to confidently build software nearshore

We Deliver Every Sprint

Icon illustrating the advantage of time zone-aligned software developers from Azumo, ensuring work hours synchronized with client schedules.

Time Zone Aligned

Our nearshore developers collaborate with you throughout your working day.

Icon showcasing the advantage of hiring expert engineers from Azumo for software development services.

Experienced Engineers

We hire mid-career software development professionals and invest in them.

Icon symbolizing how Azumo's software developers prioritize honest, English-always communication for building quality software.

Transparent Communication

Good software is built on top of honest, english-always communication.

Icon representing how Azumo's developers enhance velocity by approaching software development with a problem solver's mindset.

We Build Like Owners

We boost velocity by taking a problem solvers approach to software development.

Icon illustrating how Azumo's quality assurance process ensures the delivery of reliable, working code for every project.

You Get Consistent Results

Our internal quality assurance process ensures we push good working code.

Icon depicting how Azumo follows strict project management principles to stay aligned with your goals throughout the development process.

Agile Project Management

We follow strict project management principles so we remain aligned to your goals