or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-system.mdcli-commands.mdconfiguration.mdcore-api.mdenvironment.mdindex.mdinstallation.mdpackage-management.mdplugins.md
tile.json

tessl/pypi-poetry

Python dependency management and packaging made easy.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/poetry@2.1.x

To install, run

npx @tessl/cli install tessl/pypi-poetry@2.1.0

index.mddocs/

Poetry

Poetry is a comprehensive Python dependency management and packaging tool that modernizes Python project setup by replacing traditional files (setup.py, requirements.txt, setup.cfg, MANIFEST.in, Pipfile) with a single pyproject.toml configuration file. It provides declarative dependency management with semantic versioning support, automatic virtual environment handling, and integrated build system capabilities.

Package Information

  • Package Name: poetry
  • Language: Python
  • Installation: pip install poetry
  • CLI Tool: poetry command available after installation

Core Imports

from poetry.factory import Factory
from poetry.poetry import Poetry
from poetry.config.config import Config

For environment management:

from poetry.utils.env import EnvManager

For plugin development:

from poetry.plugins.plugin import Plugin
from poetry.plugins.application_plugin import ApplicationPlugin

Basic Usage

Programmatic Poetry Instance Creation

from poetry.factory import Factory
from pathlib import Path

# Create Poetry instance from project directory
poetry = Factory().create_poetry(cwd=Path("/path/to/project"))

# Access project configuration
print(f"Project: {poetry.package.name}")
print(f"Version: {poetry.package.version}")

# Access dependencies
for dependency in poetry.package.all_requires:
    print(f"Dependency: {dependency.name} {dependency.constraint}")

Configuration Management

from poetry.config.config import Config

# Access global configuration
config = Config.create()

# Get configuration values
cache_dir = config.get("cache-dir")
venv_path = config.get("virtualenvs.path")

# Configure package sources
config.merge({
    "repositories.my-repo": {
        "url": "https://my-package-repo.com/simple/"
    }
})

Virtual Environment Management

from poetry.utils.env import EnvManager
from pathlib import Path

# Create environment manager
env_manager = EnvManager(Path("/path/to/project"))

# Get or create virtual environment
env = env_manager.create_venv()

# Execute command in environment
env.execute("python", "-m", "pip", "list")

Architecture

Poetry's architecture consists of several core components:

  • Poetry Class: Central project representation providing access to configuration, dependencies, and build system
  • Factory: Creates and configures Poetry instances and related components
  • Configuration System: Manages global and project-specific settings
  • Package Management: Handles dependency resolution, lock files, and repository access
  • Installation System: Orchestrates package installation and virtual environment management
  • Plugin System: Enables extensibility through plugin interfaces
  • Build System: Provides PEP 517/518 compliant building and publishing
  • CLI Framework: Command-line interface built on Cleo framework

This modular design enables Poetry to serve as both a comprehensive CLI tool and a programmatic library for Python project management, dependency handling, and packaging operations.

Capabilities

Core API

Core Poetry classes and factory methods for creating and managing Python projects programmatically. Includes the main Poetry class, Factory for instance creation, and basic project operations.

class Poetry:
    def __init__(self, file: Path, local_config: dict, package: ProjectPackage, 
                 locker: Locker, config: Config, disable_cache: bool = False): ...
    def set_locker(self, locker: Locker) -> Poetry: ...
    def set_pool(self, pool: RepositoryPool) -> Poetry: ...
    def set_config(self, config: Config) -> Poetry: ...
    def get_sources(self) -> list[Source]: ...

class Factory:
    def create_poetry(self, cwd: Path | None = None, with_groups: bool = True, 
                     io = None, disable_plugins: bool = False, 
                     disable_cache: bool = False) -> Poetry: ...
    def create_pool(self, config: Config, sources = None, io = None, 
                   disable_cache: bool = False) -> RepositoryPool: ...

Core API

Configuration Management

Comprehensive configuration system for managing Poetry settings, package sources, and environment preferences. Handles both global and project-specific configuration options.

class Config:
    def get(self, setting_name: str, default = None): ...
    def merge(self, config: dict) -> Config: ...
    def all(self) -> dict: ...
    @staticmethod
    def create(reload: bool = False) -> Config: ...

class Source:
    name: str
    url: str
    priority: str
    def to_dict(self) -> dict: ...

Configuration Management

Package Management

Dependency resolution, lock file management, and repository handling. Provides complete control over project dependencies and package sources.

class Locker:
    def is_locked(self) -> bool: ...
    def is_fresh(self) -> bool: ...
    def locked_repository(self) -> Repository: ...
    def set_lock_data(self, root, packages) -> None: ...

class RepositoryPool:
    def add_repository(self, repository, priority = "supplemental") -> None: ...
    def has_primary_repositories(self) -> bool: ...

Package Management

Environment Management

Virtual environment creation, management, and execution. Handles Python interpreter selection and isolated execution environments.

class EnvManager:
    def create_venv(self) -> VirtualEnv: ...
    def get_system_env(self) -> SystemEnv: ...

class VirtualEnv:
    def execute(self, *args, **kwargs): ...
    @property
    def python(self) -> str: ...

def build_environment(poetry: Poetry, env: Env, io) -> Env: ...
def ephemeral_environment() -> Env: ...

Environment Management

Installation System

Package installation orchestration, dependency resolution, and operation management. Coordinates the installation of packages into environments.

class Installer:
    def set_package(self, package) -> Installer: ...
    def set_locker(self, locker) -> Installer: ...
    def run(self) -> int: ...

class Install:
    def __init__(self, package): ...

class Update:
    def __init__(self, initial, target): ...

Installation System

Plugin System

Extensibility interfaces for creating Poetry plugins. Enables custom commands, functionality extensions, and integration with external tools.

class Plugin:
    def activate(self, poetry: Poetry, io) -> None: ...

class ApplicationPlugin:
    commands: list
    def activate(self, application) -> None: ...

Plugin System

Build System

PEP 517/518 compliant build backend for creating wheel and source distributions. Integrates with Python packaging standards for distribution creation.

def build_wheel(wheel_directory: str, config_settings: dict = None, 
               metadata_directory: str = None) -> str: ...
def build_sdist(sdist_directory: str, config_settings: dict = None) -> str: ...
def get_requires_for_build_wheel(config_settings: dict = None) -> list: ...
def get_requires_for_build_sdist(config_settings: dict = None) -> list: ...

Build System

CLI Commands

Command-line interface providing comprehensive project management through terminal commands. Includes all Poetry CLI functionality for project creation, dependency management, and publishing.

class Application:
    def main(self) -> int: ...

class Command:
    def set_poetry(self, poetry: Poetry) -> None: ...
    def reset_poetry(self) -> None: ...

Available commands: add, build, check, config, init, install, lock, new, publish, remove, run, search, show, sync, update, version, and many subcommands.

CLI Commands

Common Types

from pathlib import Path
from typing import Any, Dict, List, Optional

class ProjectPackage:
    """Represents a Poetry project package with metadata and dependencies."""
    name: str
    version: str
    all_requires: List[Dependency]

class Dependency:
    """Represents a package dependency with constraints."""
    name: str
    constraint: str

class TOMLFile:
    """TOML file handler for reading and writing configuration files."""
    path: Path
    def read(self) -> dict: ...
    def write(self, data: dict) -> None: ...

class PyProjectTOML:
    """Enhanced pyproject.toml handler with Poetry-specific functionality."""
    file: TOMLFile
    data: dict
    def save(self) -> None: ...

Error Handling

Poetry raises specific exceptions for different error conditions:

class PoetryError(Exception):
    """Base exception for Poetry-specific errors."""

class EnvError(Exception):
    """Environment-related errors."""

class EnvCommandError(EnvError):
    """Command execution errors in environments."""

Common error scenarios include missing pyproject.toml files, dependency resolution conflicts, environment creation failures, and network issues during package operations.