python-poetry / poetry

Code

Understand python-poetry/poetry's source layout and find a starting point for your task using the saved repository evidence.

Detailed import-graph metrics were not captured for this report.

How the code fits together

CLI & CommandsUser-facing command-line interface and individual command handlers.
Dependency Resolution & InstallationCore logic for resolving dependencies and managing package installations.
Project & ConfigurationManages Poetry project metadata, configuration sources, and pyproject.toml parsing.
Package Inspection & MetadataAnalyzes packages and wheels to extract metadata and dependencies.
Build & DistributionHandles building and publishing distributions.

Files at 38a86661d2ae · descriptions are AI-written.

The descriptions and the file list come from different revisions. Check responsibilities against source.

Where to start reading

Repository root
Repository root
Public API candidatename match
Public API candidatename match
Runtime candidatename match

Find files for a task

Add a new CLI command

Suggested by the saved analysis. Some step paths were not captured or refer to generated or vendor files; only observed source files are linked.

Add support for a new package repository source

Suggested by the saved analysis. Verify the proposed change against these source files.

Extend source.py or create new source type class
Implement source discovery and credential handling in config system
Update installer to use new source during dependency resolution
Add source configuration commands (add/remove/show) to src/poetry/console/commands/source/

Customize dependency resolution behavior

Suggested by the saved analysis. Verify the proposed change against these source files.

Review and modify resolver constraints in installer.py
Update chooser.py to change package selection criteria
Add custom validation in executor.py if needed for environment-specific logic

Extend configuration schema and handling

Suggested by the saved analysis. Verify the proposed change against these source files.

Add new configuration keys to the configuration schema
Create or update config source (file or dict) to read new keys
Implement config get/set commands in console/commands/config.py

Change the public API

Start with possible export surfaces, then check their consumers and tests. These suggestions use file names, not verified execution paths.

File-name match for this task.
File-name match for this task.
File-name match for this task.

Trace runtime behavior

Start with possible startup or request handlers, then follow the calls for your scenario. These suggestions use file names, not verified execution paths.

File-name match for this task.

Add or update tests

Use a nearby test as a pattern. Read the root manifest or contribution guide for the correct test command. These suggestions use file names, not verified execution paths.

File-name match for this task.
File-name match for this task.
File-name match for this task.

Change build or automation

Inspect the relevant configuration and the commands it runs before changing the workflow. These suggestions use file names, not verified execution paths.

File-name match for this task.
File-name match for this task.
File-name match for this task.

File paths come from a snapshot of up to 500 captured paths; an omitted file may still exist.

Public and runtime candidates are based on file names; their exports and execution paths still need checking in source.
The file list was refreshed after the written analysis. Subsystem descriptions and suggested changes may describe an older revision.

Architecture and request flow

Start here — files every contributor must understand

AI · unverified

src/poetry/__main__.py

Entry point that initializes and runs the Poetry CLI application.

src/poetry/console/application.py

Core CLI application orchestrator that loads commands and handles console interactions.

src/poetry/factory.py

Factory for instantiating Poetry project instances from pyproject.toml and configuration.

src/poetry/installation/installer.py

Primary orchestrator for dependency resolution and package installation operations.

src/poetry/config/config.py

Configuration management system that reads and caches Poetry settings from multiple sources.

src/poetry/console/command_loader.py

Dynamically loads and registers CLI commands available to the Poetry application.

src/poetry/inspection/info.py

Analyzes and extracts metadata from Python packages and wheels for dependency inspection.

Request flow

Technology choices

Python CLI framework (likely Cleo/Click-based)

Provides structured command parsing, help text, and argument handling for a large command surface

pyproject.toml (PEP 517/518/621 standards)

Single canonical source of truth for project metadata and build requirements, replacing fragmented setup.py/requirements.txt files

Lock file (poetry.lock)

Ensures reproducible, deterministic dependency resolution across environments and machines

Plugin/extension system (command_loader, self commands)

Allows extending Poetry functionality without modifying core codebase

Build time and runtime

Build-time

▸
Poetry Core masonry.api — PEP 517 build backend that creates wheels and source distributions during poetry build
▸
Dependency resolution engine — Resolves version constraints and generates lock file during poetry lock/install
▸
pyproject.toml parsing — Parses and validates project metadata and build configuration at startup

Runtime

▸
CLI command dispatcher — Routes user input to appropriate command handlers and executes them
▸
Package executor — Installs/uninstalls resolved packages into target Python environment
▸
Configuration manager — Loads and caches Poetry settings from multiple sources during execution
▸
Package inspection — Extracts metadata from packages to resolve dependencies and validate compatibility

Design trade-offs

Unified lock file instead of multiple requirements.txt files

Reduces complexity and version conflicts

Requires all dependencies to be managed through Poetry; less granular control per environment

Central configuration file instead of per-project overrides

Simpler to reason about and maintain consistency

Less flexibility for per-project configuration without editing central config

Lazy wheel inspection with lazy_wheel.py

Avoid downloading entire wheels for metadata extraction

Complex logic to extract metadata without full download; potential for incomplete metadata in edge cases

Non-goals

✗Does not manage system-level Python installations (delegates to external tools)
✗Does not handle authentication to private registries beyond basic credential storage
✗Does not provide real-time package monitoring or vulnerability scanning
✗Does not manage non-Python project dependencies

Code quality and hotspots

Quality Score: 80/100

Low Risk

This repo is in good health with CI, tests, and active maintenance.

High complexity -10Multiple anti-patterns -10

Maintainability grade

Static analysis

How maintainable the code looks — from complexity, code issues, test presence, file size, and hotspot load. It grades the shape of the code, not defect risk, and doesn't replace review.

60/100

A ≥ 85, B ≥ 70, C ≥ 55, D ≥ 40, F < 40

Cyclomatic complexityavg 29

2/35

Code issues0 errors, 7 warnings

17/20

Testspresent · ~100% of files

20/20

Largest file1,135 lines

11/15

Hotspot load0 high-risk files

10/10

Configuration status

CI/CD Pipeline — configured

Provider: GitHub Actions

6 GitHub Actions workflows

Test Suite — detected

784 test files detected

Stack: Pytest

Where: tests/console/commands/env · tests/console/commands/self · tests/config

Test Coverage — ~100%heuristic

784 test files / 193 source files. This is a file-count ratio, not real line coverage — set up Codecov for authoritative numbers.

Dependency Scanning — 1 tool configured

Dependabot

Top hotspots

Files edited often AND hard to reason about. Churn = recent commit frequency, Complexity = branches and nesting, Risk = both combined. These are the highest-leverage targets for refactoring or testing.

repositories/http_repository.py

Churn: 32 (8 commits/180d)Complexity: 90Risk: 29

installation/executor.py

Churn: 28 (7 commits/180d)Complexity: 100Risk: 28

All hotspots

Files that change often and are complex tend to accumulate more bugs

AI-suggested anti-patterns

AI · unverified

Pattern-matches from the file structure and dependencies — useful as hypotheses, but not grounded in actual source. For real findings see Code Scanning above.

Tight coupling between commands and installer

Medium

Multiple commands directly instantiate and configure Installer with similar logic, duplicating initialization and validation code.

src/poetry/console/commands/install.py, src/poetry/console/commands/update.py, src/poetry/console/commands/lock.py

Global configuration mutable state

Low

Configuration is cached at module level and modified in place, risking state leakage between operations in long-running processes.

src/poetry/config/config.py

Exception handling too broad

Medium

Catching generic Exception instead of specific Poetry/pip exceptions makes debugging and error recovery difficult.

src/poetry/installation/executor.py, src/poetry/installation/installer.py

AI-suggested bottlenecks

AI · unverified

Speculation from file structure, not profiling data. Validate against real metrics before acting on these.

CPU/Algorithm Bottleneck

Dependency resolution is single-threaded; large dependency trees may block on constraint solving.

src/poetry/installation/installer.py

I/O network Bottleneck

Lazy wheel inspection requires HTTP range requests; slow or unreliable networks cause metadata extraction delays.

src/poetry/inspection/lazy_wheel.py

I/O parallelization Bottleneck

Package installation serializes operations; could parallelize independent package installs.

src/poetry/installation/executor.py

Code metrics

Static analysis on sampled source files (up to 15 files).

Avg Cyclomatic Complexity29

Counts if/for/while/switch/catch/ternary branches

Errors / Warnings0 / 7

Secrets, empty catches, console.log, var usage, long lines

Largest File Analyzed1135 lines

src/poetry/puzzle/provider.py