python-poetry/poetry
61.8
Adequate · 15 November 2026
21.9k
lines of production code
Python
primary language
5
measurements over time
What this system is
Features
Add self show and self show plugins commands
Users can now inspect Poetry's own runtime environment using the new \self show\ command, which lists all installed packages and supports filtering for add-on packages via the \--addons\ flag. Additionally, the \self show plugins\ command provides a detailed view of currently installed Poetry plugins, including their versions, descriptions, and specific plugin entry points (both application and standard plugins) along with their dependencies.
src/poetry/console/commands/self/show · high confidence
Introduce Python management commands
Users can now manage Python installations directly via Poetry using new commands: \poetry python install\ to download and install specific Python versions (including free-threaded builds), \poetry python list\ to view available and installed versions, and \poetry python remove\ to uninstall managed versions. These commands are currently experimental and allow Poetry to handle its own Python runtime dependencies.
src/poetry/console/commands/python · high confidence
Introduce dedicated Python management subsystem
Poetry now includes a new, dedicated module for managing Python interpreters, located in \src/poetry/utils/env/python\. This subsystem introduces a \Python\ class that leverages the \findpython\ library to discover and manage available Python versions, including support for free-threaded Python. It also provides a \PythonInstaller\ class that uses \pbs\_installer\ to download and install specific Python versions (CPython and PyPy) into Poetry's managed installation directory, along with corresponding exception classes to handle version mismatches and installation failures. This change centralizes Python discovery and installation logic, separating it from the general environment management code.
src/poetry/utils/env/python · high confidence
Introduce lazy wheel metadata retrieval
Added a new lazy-wheel mechanism that fetches package metadata from remote wheels using HTTP range requests, allowing Poetry to read metadata without downloading the entire wheel file. This change improves performance and reduces bandwidth usage when inspecting remote packages, while also including robust error handling for servers that do not properly support range requests.
src/poetry/inspection · high confidence
Introduce src layout support for new projects
Users can now choose between a standard layout and a src layout when creating new projects via \poetry new\ or \poetry init\. The \src\ layout places the package code inside a \src/\ directory, which is a common best practice for isolation, while the \standard\ layout keeps it in the root. This is implemented via a new \poetry.layouts\ module that registers these two layout types and handles the generation of the corresponding directory structure and \pyproject.toml\ configuration.
src/poetry/layouts · high confidence
New cache management commands: cache clear and cache list
Users can now manage Poetry's local cache using two new commands. The \cache list\ command displays all available cache directories. The \cache clear\ command allows users to clear specific cache entries by specifying a package name and version (e.g., \cache clear pypi:requests:2.28.0\), or clear all entries within a specific cache type (e.g., \cache clear pypi --all\) or all caches entirely (e.g., \cache clear --all\). Clearing all entries requires confirmation.
src/poetry/console/commands/cache · high confidence
New debug commands for environment info, dependency resolution, and compatibility tags
Users can now run \poetry debug info\ to view Poetry version, Python version, and installation paths; \poetry debug resolve\ to debug dependency resolution with options to display the dependency tree or simulate installation; and \poetry debug tags\ to show compatible platform tags for the current environment.
src/poetry/console/commands/debug · high confidence
New self-management commands for Poetry's runtime environment
Poetry now provides a dedicated set of commands under the \self\ namespace to manage its own runtime environment and packages. Users can add, remove, install, lock, sync, and update Poetry itself or its additional dependencies using commands like \poetry self add\, \self remove\, \self install\, \self lock\, \self sync\, and \self update\. These commands operate on a system-level \pyproject.toml\ located in Poetry's configuration directory, allowing users to extend Poetry's capabilities with extra packages without affecting their project dependencies.
src/poetry/console/commands/self · high confidence
Project-specific plugin management via \`tool.poetry.requires-plugins\`
Poetry now supports declaring required plugins in the \tool.poetry.requires-plugins\ section of \pyproject.toml\. When running \poetry install\, any plugins not already present in Poetry's main environment are installed into a project-local \.poetry/plugins\ directory. This directory is added to the front of \sys.path\ (and processed for \.pth\ files) so that these plugins are discovered and activated before global ones, allowing projects to enforce specific plugin versions or behaviors without affecting the global Poetry installation.
src/poetry/plugins · high confidence
Architecture
Refactored environment management into modular components
The environment management logic in \src/poetry/utils/env\ has been restructured into separate modules (\base\_env\, \env\_manager\, \virtual\_env\, \system\_env\, \generic\_env\, \site\_packages\, etc.) to improve maintainability and separation of concerns. This change introduces a new \EnvManager\ class to handle virtual environment creation and activation, and refactors the \Env\ base class and its subclasses to provide a cleaner interface for environment discovery and management. Users will benefit from more robust environment handling, including better support for system site packages and improved error messages during environment operations.
src/poetry/utils/env · high confidence
Refactored utility modules into a new src/poetry/utils package
The codebase has been reorganized to move utility logic into a dedicated \src/poetry/utils\ package. This change introduces new modules for handling compatibility (\\_compat\), caching (\cache\), HTTP authentication (\authenticator\), dependency specification parsing (\dependency\_specification\), file downloads (\download\), and isolated builds (\isolated\_build\). Users benefit from improved thread safety in cached properties, better handling of HTTP credentials and certificate configurations, and more robust dependency resolution for VCS and URL-based sources.
src/poetry/utils · high confidence
Repository layer refactored with new abstract base and prioritized pool
The repository module has been restructured to introduce an AbstractRepository base class and a new RepositoryPool that manages repositories with explicit priority levels (Primary, Supplemental, Explicit). This change replaces the previous pool implementation, altering how package sources are ordered and searched, and introduces new exception classes (RepositoryError, PackageNotFoundError, InvalidSourceError) for better error handling within the repository layer.
src/poetry/repositories · high confidence
Behavioural changes
Dependency resolution engine refactored and performance-optimized
The dependency resolution logic in src/poetry/mixology has been significantly refactored to improve performance and reliability. The solver now employs a more efficient caching strategy for dependencies, reducing redundant lookups during the resolution process. Additionally, the error reporting for version conflicts has been enhanced to provide clearer, more actionable messages to users when dependency constraints cannot be satisfied.
src/poetry/mixology · high confidence
Dependency resolution engine restructured with new Provider and Transaction components
The dependency solving logic in the puzzle module has been reorganized into distinct components: a new Provider class handles package source lookups and marker merging, a Solver class orchestrates the resolution process using the Provider, and a Transaction class calculates the final installation operations. This refactoring introduces support for marker-splitting to resolve mutually exclusive dependency constraints, improves handling of extras and markers during installation, and adds progress indicators for dependency resolution.
src/poetry/puzzle · high confidence
Editable installs now use a dedicated builder with improved script handling
The masonry module now includes a dedicated \EditableBuilder\ that manages editable installations by generating \.pth\ files and console/GUI scripts directly in the environment, rather than relying on pip's editable wrapper. This change ensures that scripts defined in \\[tool.poetry.scripts\]\ are correctly installed and executed, fixing issues where they were previously not copied to the bin directory or failed when extras were involved. Users will see more reliable editable installs with proper script availability and better error messages for malformed script definitions.
src/poetry/masonry · high confidence
Git operations now disable terminal prompts and enforce strict parameter validation
The Git subsystem in src/poetry/vcs/git/system.py has been updated to prevent interactive prompts during version control operations by setting the GIT\_TERMINAL\_PROMPT environment variable to 0. Additionally, the SystemGit class now validates input parameters to reject any arguments starting with a hyphen, preventing potential command injection or unintended code execution. These changes ensure that Git commands run non-interactively and safely within automated environments.
src/poetry/vcs · high confidence
Introduce structured logging formatters for build operations
Users will now see build-related log messages (such as building, built, adding, and executing build scripts) formatted with consistent indentation and syntax highlighting (e.g., \<info\>, \<success\>, \<b\> tags) rather than raw text. This is achieved by introducing a new \BuilderLogFormatter\ class and a registry (\FORMATTERS\) that maps specific masonry builder loggers to this formatter, ensuring a cleaner and more readable console output during package builds.
src/poetry/console/logging/formatters · high confidence
Migration to pyproject.toml and modern pre-commit configuration
The project configuration has moved from the legacy \poetry.toml\ file to the standard \pyproject.toml\ format, aligning with modern Python packaging practices. Additionally, the development workflow now uses a comprehensive \pre-commit-config.yaml\ that integrates \ruff\ for linting and formatting, \zizmor\ for security checks, and custom \poetry-check\, \poetry-lock\, and \poetry-install\ hooks to validate configuration and manage dependencies automatically.
(repo-wide) · high confidence
Migration to src layout and introduction of build constraints
Poetry has migrated its source code to a standard src layout, moving modules under the src/poetry directory and updating the entry point in \_\main\\_.py. This release also introduces support for specifying build constraints for dependencies via the build-constraints configuration, allowing users to define specific dependency versions for isolated build environments. Additionally, the project now uses platformdirs for locating configuration and cache directories, replacing the previous appdirs dependency, and includes a py.typed marker file to enable static type checking for consumers of the library.
src/poetry · high confidence
New package management module with lock file v2.1 support
The \src/poetry/packages\ module has been restructured into a dedicated package, introducing new classes to manage dependency resolution and lock file handling. \DependencyPackage\ and \PackageCollection\ now encapsulate the relationship between dependencies and their resolved packages, while \DirectOrigin\ handles fetching packages from Git, URLs, and directories, including file size metadata. The \Locker\ class has been updated to support lock file format version 2.1, which stores package file hashes and sizes directly in the lock file, supports dependency groups with specific markers, and includes a \@generated\ comment header. Additionally, \TransitivePackageInfo\ provides structured data for transitive dependency analysis, including depth and group-specific markers.
src/poetry/packages · high confidence
New structured console logging with third-party log prefixing
The console logging subsystem has been refactored to use a new \IOHandler\ and \IOFormatter\ that integrate with Cleo's IO interface. This change ensures that log messages from third-party packages are prefixed with their source module or package name (e.g., \\[requests:connectionpool\]\) to improve debuggability, while Poetry's own logs remain unadorned. The formatter also applies color coding based on log level (red for errors, yellow for warnings, etc.) and supports custom formatting for specific log sources.
src/poetry/console/logging · high confidence
New version selection logic with strict prerelease handling
The version resolution process has been refactored into a dedicated \VersionSelector\ class that explicitly manages prerelease availability. Users will now experience stricter enforcement of the \allow-prereleases\ setting: prereleases are ignored by default unless no stable versions are available, and setting the flag to \false\ will actively forbid prereleases even when they are the only candidates. This change ensures more predictable dependency resolution by preventing unintended inclusion of unstable package versions.
src/poetry/version · high confidence
Poetry 2.0 CLI overhaul: new commands, removed shell, and Cleo 2.0 upgrade
This change introduces the Poetry 2.0 command-line interface, built on Cleo 2.0. The old \poetry shell\ command is removed and replaced by the new \poetry env activate\ command. Several new commands are added: \poetry sync\ (replacing \install --sync\), \poetry python\ (for managing Python versions), \poetry debug tags\, and a suite of \poetry self\ commands (\add\, \remove\, \install\, \lock\, \show\, \sync\). Global options include \--no-cache\ to disable caching and \--directory\/\-C\ to specify the working directory. The application now handles command-not-found errors with specific messages for removed or moved commands (like \shell\).
src/poetry/console · high confidence
Poetry v2 CLI commands restructured and migrated to Cleo 2.0
The CLI command implementations in src/poetry/console/commands have been rewritten for Poetry v2, migrating from the legacy CLI framework to Cleo 2.0. This introduces a new base Command class that explicitly manages the Poetry instance via set\_poetry, and refactors command hierarchies (e.g., InstallerCommand now inherits from both GroupCommand and EnvCommand). The diff shows the addition of new commands and options such as --all-extras and --only-root for install, --regenerate for lock, and --migrate for config, alongside the deprecation of legacy flags like --sync and --dev. These changes represent a complete overhaul of the command-line interface structure and behavior.
src/poetry/console/commands · high confidence
Publishing module refactored into src layout with FIPS-compatible hashing
The publishing logic has been reorganized into the src layout, introducing dedicated modules for the Publisher, Uploader, and HashManager. A key behavioral change is the HashManager's ability to operate in FIPS environments by gracefully handling disabled MD5 and BLAKE2 algorithms, ensuring uploads do not fail on restricted systems. Additionally, the uploader now computes and includes blake2\_256 digests in upload metadata alongside MD5 and SHA-256, and the publisher normalizes legacy repository URLs to ensure consistent endpoint resolution.
src/poetry/publishing · high confidence
Refactor environment management commands into a modular subcommand structure
The environment management commands have been reorganized from a monolithic structure into distinct, modular subcommands (\env activate\, \env info\, \env list\, \env remove\, \env use\). This change introduces specific behaviors for each subcommand: \env activate\ now detects the current shell and prints the appropriate activation script command (supporting bash, zsh, fish, powershell, etc.), \env info\ displays detailed virtualenv and base environment information with optional path/executable filters, \env list\ shows associated virtualenvs with an optional full-path flag, \env remove\ handles deletion of specific or all virtualenvs including cleanup of the envs.toml file, and \env use\ manages activation or creation of new virtualenvs. This modularization improves command clarity and allows for more targeted environment operations.
src/poetry/console/commands/env · high confidence
Refactor installation operations to use PEP 563 postponed annotations
The installation operation classes (Install, Uninstall, Update, and the Operation base class) now use postponed evaluation of annotations (from \_\future\\_ import annotations). This change simplifies type hint syntax by allowing forward references without quotes and improves compatibility with modern Python typing features, such as using typing\_extensions.Self for better method chaining support in the base Operation class.
src/poetry/installation/operations · high confidence
Refactor source management commands to use the new Source class and Priority enum
The source management commands (add, remove, show) have been refactored to use the dedicated Source class and the new Priority enum, replacing previous inline logic. This change introduces a warning when adding a source without specifying priority, indicating that the default will shift to 'supplemental' in a future release, and enhances the 'source show' command to explicitly notify users when PyPI is implicitly enabled as a primary source.
src/poetry/console/commands/source · high confidence
Refactored TOML handling to align with poetry-core exception hierarchy
The TOML file handling logic has been restructured to integrate with the updated poetry-core exception system. A new custom TOMLError is now raised for invalid TOML files, inheriting from both PoetryCoreError and TOMLKitError to ensure compatibility with the core library's error hierarchy. The TOMLFile class wraps the underlying tomlkit file reader, providing a consistent interface for reading and validating TOML configuration files while surfacing these standardized errors to the user.
src/poetry/toml · high confidence
Refactored link source parsing with lazy evaluation and PEP 691 JSON support
The link source parsing logic in src/poetry/repositories/link\_sources has been restructured to improve performance and support modern repository APIs. The new implementation introduces lazy evaluation for Link objects, deferring their construction until a specific version is actually needed, which significantly reduces memory usage and startup time for large repositories. It also adds native support for the PEP 691 JSON-based Simple API via the new SimpleJsonPage class, allowing Poetry to leverage structured metadata (such as hashes, size, and upload time) directly from JSON responses. Additionally, the HTML parsing logic has been updated to handle PEP 658 metadata flags and PEP 714 core-metadata indicators, ensuring compatibility with updated repository standards while maintaining backward compatibility with existing HTML-based simple repositories.
_src/poetry/repositories/link\sources · high confidence
Removal of legacy semver module and introduction of new exception and Git handling infrastructure
This change removes the internal \poetry/semver\ module, which previously handled version parsing and constraint matching, and replaces it with new infrastructure files. Specifically, it introduces \src/poetry/console/exceptions.py\ with a new \PoetryRuntimeError\ class and \ConsoleMessage\ helper for structured, formatted error output. It also adds \src/poetry/vcs/git/backend.py\, which implements Git operations using the \dulwich\ library instead of the system \git\ command, including support for FIPS-compliant hashing in \src/poetry/publishing/hash\_manager.py\ and improved error handling for Git submodules and authentication. Additionally, test fixtures for distribution hashes and PyPI metadata generation are updated to reflect these changes.
poetry · high confidence
Replace pip-based installation with a native wheel installer and builtin uninstaller
Poetry now installs packages using a native wheel installer (via the \installer\ library) instead of invoking \pip\ as a subprocess, and includes a built-in uninstaller that removes files directly without relying on \pip uninstall\. This change improves installation performance, reduces subprocess overhead, and allows for features like bytecode compilation control and better error reporting during the install and uninstall phases.
src/poetry/installation · high confidence
Reworked configuration system with new default settings and migration support
The configuration subsystem has been refactored to introduce a new \ConfigSource\ abstraction with dedicated \DictConfigSource\ and \FileConfigSource\ implementations, enabling structured configuration management. This change updates default settings, notably setting \installer.re-resolve\ to \false\ by default and enabling \solver.lazy-wheel\ by default, while adding new configuration options such as \installer.builtin-uninstall\, \installer.build-config-settings\, and \keyring.enabled\. A new \ConfigSourceMigration\ mechanism is included to handle key renames and value transformations, ensuring backward compatibility for existing user configurations during upgrades.
src/poetry/config · high confidence
Switch to fastjsonschema for Poetry JSON validation
The JSON schema validation in src/poetry/json now uses the fastjsonschema library instead of the previous implementation. This change introduces caching for the compiled validator and properties to improve performance, and updates the validation logic to check for additional properties not defined in the Poetry or core schemas, returning specific error messages for unexpected keys.
src/poetry/json · high confidence
Test coverage
Add test fixtures for git-based demo packages; Added comprehensive test suite for repository modules; Added comprehensive test suite for the version solver; Added console test suite and fixtures; Added installation lock-file fixtures for Poetry 2.1; Added installation test suite; Added integration tests for the Git VCS backend; Added legacy project fixture for PEP 639 and PEP 621 compatibility tests; Added legacy repository test fixtures; Added test coverage for config system components; Added test coverage for console commands; Added test coverage for publishing components; Added test coverage for the \poetry self\ command suite; Added test fixture files for simple\_project; Added test fixture for a project using setup.py; Added test fixture for building C extensions without a setup.py; Added test fixture for excluded subpackage handling; Added test fixture for excluded subpackage versioning; Added test fixture for extended project with custom build logic; Added test fixture for extended project without setup.py; Added test fixture for git URL subdirectory resolution; Added test fixture for missing build system requirements; Added test fixture for multi-constraints dependencies; Added test fixture for multiple README files; Added test fixture for multiple dist-dir scenarios; Added test fixture for non-canonical package name validation; Added test fixture for package with include configuration; Added test fixture for poetry-plugin package; Added test fixture for setup.py calling external scripts; Added test fixtures for PEP 610 and editable installations; Added test fixtures for a no-dependencies demo project; Added test fixtures for file scripts handling; Added test fixtures for forked git repository subdirectories; Added test fixtures for git URL subdirectory support; Added test fixtures for invalid \[tool.poetry.scripts\] entries; Added test fixtures for package inspection edge cases; Added test fixtures for project plugin scenarios; Added test fixtures for script execution behavior; Added test fixtures for transitive dependencies; Added test fixtures for various build system configurations; Added test suite for mixology dependency resolution logic; Added test suite for utils module; Added tests for Python environment management and installation; Added tests for Python management commands; Added tests for TOML file management; Added tests for cache clear and list commands; Added tests for console logging formatters; Added tests for debug info and resolve commands; Added tests for link source parsing logic; Added tests for package inspection and lazy wheel metadata retrieval; Added tests for package locking, direct origin handling, and transitive package info; Added tests for pyproject.toml parsing and configuration handling; Added tests for pyproject.toml schema validation; Added tests for the Git VCS backend and system modules; Added tests for the editable builder; Added tests for the env console commands; Added tests for the plugin manager and project plugin caching; Added tests for virtual environment management and site packages handling; Added unit tests for the dependency puzzle solver; Initial test infrastructure and fixtures for Poetry; New test fixtures for repository mocking; Removed legacy semver test suite; Updated PyPI repository test fixtures; Updated test fixtures for installed package detection; Updated test fixtures for installed packages.
Dependencies
Poetry 2.5.1 release with PEP 621 migration and dependency updates
This release updates Poetry to version 2.5.1 and migrates the project's own configuration to PEP 621 standard format, moving dependency declarations from the legacy \\[tool.poetry.dependencies\]\ section to the standard \\[project.dependencies\]\ array. The build system now requires \poetry-core\>=2.0\, and the dependency list has been refreshed with updated version constraints for core libraries such as \cleo\, \dulwich\, \fastjsonschema\, \installer\, \keyring\, \packaging\, \platformdirs\, \requests\, \virtualenv\, and \findpython\. Additionally, new dependencies \pbs-installer\ and \trove-classifiers\ have been added to support modern build and metadata standards.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 61 → 62 (+0.6)
- Rubric changed (rubric-2026.11.1 → rubric-2026.11.4) — scores are not directly comparable.
Lenses
- Code Health 73 → 70 (-3.2)
- Architecture 84 → 96 (+11.5)
- Maturity 48 → 50 (+1.8)
- Readiness 70 → 73 (+3.7)
- Security 78 → 70 (-7.8)
Resolved (10)
- Further sole-owners (lower concentration)
- High CVE: [GHSA redacted] (poetry.lock)
- High CVE: [GHSA redacted] (poetry.lock)
- No ADRs found
- Off-boarding risk: anonymized user #1
- Orphaned file (src/poetry/console/commands/version.py)
- Orphaned file (src/poetry/publishing/publisher.py)
- Orphaned file (src/poetry/repositories/parsers/pypi_search_parser.py)
- Orphaned file (src/poetry/utils/env/init.py)
- Projects may be oversized for their cohesion
New (9)
- No ADRs found (pyproject.toml)
- Off-boarding risk: anonymized user #1
- Orphaned file (src/poetry/console/commands/debug/resolve.py)
- Orphaned file (src/poetry/console/commands/python/list.py)
- Orphaned file (src/poetry/console/commands/self/self_command.py)
- Orphaned file (src/poetry/repositories/pypi_repository.py)
- Orphaned file (src/poetry/utils/cache.py)
- Orphaned file (src/poetry/utils/env/python/providers.py)
- Publisher.publish (cognitive 19) (src/poetry/publishing/publisher.py)
Changes since last survey
- 19 commits — 15 feature/other, 4 fixes
By area
- src/poetry — 5 commits
- (root) — 3 commits
- docs/cli.md — 2 commits
- docs/dependency-specification.md — 2 commits
- tests/config — 2 commits
- tests/console — 2 commits
- docs/pre-commit-hooks.md — 1 commit
- docs/repositories.md — 1 commit
- tests/repositories — 1 commit
Notable commits
- fix: fix(authenticator): handle missing URL in repository config (#11081)
- fix: fix(config): report the setting name for invalid integer values from environment variables (#11149)
- fix: fix(publish): report a comprehensible error for a missing repository url (#11114)
- fix: fix(version): do not crash on prerelease bump of a dev release (#11217)
- change: Update findpython (#11204)
- change: [pre-commit.ci] pre-commit autoupdate (#11062)
- change: chore: update dependencies (#11219)
- change: config: track validator and normalizer of each setting in one place (#11218)
- change: docs: distinguish package and upload repository URLs (#11143)
- change: docs: document the options of poetry debug resolve (#11211)
- change: docs: explain certificate configuration for system Git (#11145)
- change: docs: fix typo in InstalledRepository.get_package_paths docstring (#10990)
- change: docs: separate directory and archive path dependency examples (#11079)
- change: docs: use the plugin repo for the poetry-export pre-commit hook (#11213)
- change: test: cover IOHandler and the remaining IOFormatter branches (#11119)
- change: test: cover apply with a missing old key (#11162)
- change: test: reuse init_basic_toml fixture in new project expectations (#11163)
- change: tests: remove unnecessary if statement in test_find_packages_only_prereleases (#11210)
- change: tests: use expected priority in source tests (#11212)
Architecture
- Unchanged — 0 containers · 1 contexts · 0 edges
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
python-poetry/poetry was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 15 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 18668c8dacdbac00c6f758bd4609602122c78df4 — the exact code this score is about.
- Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.73+preprod-52de90b74216.