Introduction to Poetry for Dependency Management in Python

Importance of Dependency Management

• Prevent Version Conflicts: Ensure the correct versions of libraries/packages are used.
• Consistency: Facilitate smooth execution of scripts across different environments.

Overview of Poetry

• **Main Functionalities: **
  • Dependency management
  • Creating virtual environments
  • Publishing packages to PyPI
• Addressed Issues: Replaces older methods such as pip install and requirements.txt

Basic Concepts

Dependencies in Python

• Historically handled using pip install and requirements.txt
• Issues: Version conflicts; difficulty in tracking dependencies
• Introduction of PEP 518: pyproject.toml file
  • Single file for all project settings (name, version, dependencies, build settings)

Example pyproject.toml file

• General Package Settings: name, version, description, readme reference
• Dependencies: E.g., Python 3.12
• Build System Settings

Using Poetry

Adding Dependencies

• Simple Command: poetry add <package>
• Automatically updates pyproject.toml with dependency details
• Example: poetry add pytest
  • Adds pytest and its dependencies
  • Shows installed packages via poetry show
  • Creates poetry.lock file to track dependencies

Removing Dependencies

• Simple Command: poetry remove <package>
• Automatically removes the package from pyproject.toml

Version Control

• Adding Specific Versions: poetry add <package>@<version>
  • Example: poetry add requests@2.2.1
  • Shows version in pyproject.toml
• Version Constraints:
  • Caret (^): E.g., ^2.2 (latest version up to major version)
  • Tilde (~): E.g., ~2.2 (latest version up to minor version)
• Preferred Method: Caret ^ for good balance of control and simplicity

Viewing Dependencies

• Show Specific Package: poetry show <package>
• Show All Packages: poetry show

Virtual Environments

• Creating Virtual Environment: poetry install
• Entering Virtual Environment: poetry shell
  • Execute Python code within this environment
  • Virtual environment located in virtualenvs folder

Versioning and Publishing Packages

Versioning with Poetry

• Bump Version: poetry version <increment>
  • Uses semantic versioning (e.g., poetry version minor)
  • Updates version in pyproject.toml
• Version Labels: E.g., 1.0.0-alpha.1, 1.0.0-rc.1

Building and Publishing

• Building Package: poetry build
  • Creates distributable formats like wheel or tar.gz
• Publishing to PyPI: poetry publish --build
  • Requires PyPI credentials

Automation Possibilities

• GitHub Workflows: Automate tasks like building and publishing upon specific events (e.g., commit or tag)

Additional Resources

• Free guide to designing software from scratch: [iron.cc/designguide]