depcon

   |
 __|   _    _   __   __   _  _
/  |  |/  |/ \_/    /  \_/ |/ |
\_/|_/|__/|__/ \___/\__/   |  |_/
         /|
         \|

depcon is a modern, fully-featured tool for converting legacy requirements.txt files to the standardized pyproject.toml format with full PEP 621 support. It provides intelligent dependency grouping, validation, and seamless integration with modern Python packaging tools like uv, hatchling, and setuptools.

Features

• Full PEP 621, PEP 635 & PEP 735 Support: Complete support for modern Python packaging standards
• PEP 639 License: Generates modern license = "MIT" SPDX string format
• Intelligent Dependency Grouping: Automatically categorizes dependencies into main, dev, test, and docs groups
• PEP 735 include-group: Dependency groups can reference other groups (e.g., dev includes test)
• Proper Dependency Types: Correctly distinguishes between dependency-groups (PEP 735) and optional-dependencies (PEP 621 extras)
• Advanced Parsing: Handles complex requirements files including pip-tools, editable installs, and URLs
• Validation: Built-in dependency validation and error checking
• Multiple Build Backends: Support for hatchling, setuptools, and poetry
• Rich CLI: Beautiful command-line interface with progress indicators and summaries
• Export & Sync: Export dependencies to requirements.txt and sync between formats

Installation

Using uv (Recommended)

# Install with uv
uv tool install depcon

# Or run directly without installing
uvx depcon

Using pipx

pipx install depcon

Using pip

pip install depcon

Quick Start

Basic Conversion

Convert a simple requirements.txt file:

depcon convert -r requirements.txt

Full Project Migration

Convert multiple requirement files with proper grouping:

depcon convert \
  -r requirements.txt \
  -d requirements-dev.txt \
  -t requirements-test.txt \
  --docs-requirements requirements-docs.txt \
  --project-name "my-awesome-project" \
  --project-description "An awesome Python project"

Commands

convert - Convert requirements files to pyproject.toml

The main command for converting requirements files to modern pyproject.toml format with full PEP 621 and PEP 735 support.

Options:

• -r, --requirements PATH: Requirements files to process (requirements.txt, requirements.in)
• -d, --dev-requirements PATH: Development requirements files to process
• -t, --test-requirements PATH: Test requirements files to process
• --docs-requirements PATH: Documentation requirements files to process
• -o, --output PATH: Output pyproject.toml file path (default: pyproject.toml)
• --append / --no-append: Append to existing dependencies instead of replacing
• --backup / --no-backup: Create backup of existing pyproject.toml
• --resolve / --no-resolve: Resolve and pin dependency versions
• --sort / --no-sort: Sort dependencies alphabetically
• --build-backend [hatchling|setuptools|poetry]: Build backend to use
• --dev-group TEXT: Name for development dependencies group (default: dev)
• --test-group TEXT: Name for test dependencies group (default: test)
• --docs-group TEXT: Name for documentation dependencies group (default: docs)
• --project-name TEXT: Project name (if creating new pyproject.toml)
• --project-version TEXT: Project version (if creating new pyproject.toml)
• --project-description TEXT: Project description (if creating new pyproject.toml)
• --python-version TEXT: Python version requirement (default: >=3.12)
• --use-optional-deps / --use-dependency-groups: Use optional-dependencies (PEP 621 extras) instead of dependency-groups (PEP 735)
• --remove-duplicates / --keep-duplicates: Remove duplicate dependencies across groups (default: remove)
• --strict / --no-strict: Strict mode: fail on parsing errors instead of warning
• -v, --verbose: Enable verbose output

show - Display dependencies from pyproject.toml

Show dependencies in a formatted table.

Options:

• -f, --file PATH: Path to pyproject.toml file (default: pyproject.toml)
• --format [table|json|yaml]: Output format (default: table)
• --group TEXT: Show only specific dependency group (main, dev, test, docs, or optional group name)

validate - Validate pyproject.toml dependencies

Validate that all dependencies are properly formatted.

Options:

• -f, --file PATH: Path to pyproject.toml file (default: pyproject.toml)
• --group TEXT: Dependency group to validate (main, dev, test, docs)
• --check-pypi / --no-check-pypi: Check if packages exist on PyPI

export - Export dependencies to requirements.txt

Export dependencies from pyproject.toml to requirements.txt format.

Options:

• -f, --file PATH: Path to pyproject.toml file (default: pyproject.toml)
• -o, --output PATH: Output requirements.txt file path (default: requirements.txt)
• --group TEXT: Dependency group to export (main, dev, test, docs, or all) (default: main)
• --include-hashes: Include package hashes in output

diff - Show differences between files

Show differences between pyproject.toml and requirements files.

Options:

• -f, --file PATH: Path to pyproject.toml file (default: pyproject.toml)
• -r, --requirements PATH: Path to requirements.txt file to compare
• --group TEXT: Dependency group to compare (main, dev, test, docs)

sync - Sync dependencies to requirements files

Sync dependencies from pyproject.toml to requirements files.

Options:

• -f, --file PATH: Path to pyproject.toml file (default: pyproject.toml)
• --group TEXT: Dependency groups to sync (can be specified multiple times, default: all)
• --dry-run: Show what would be synced without making changes

list - List all dependency groups

List all dependency groups in pyproject.toml.

Options:

• -f, --file PATH: Path to pyproject.toml file (default: pyproject.toml)

check - Check for common issues

Check pyproject.toml for common issues like duplicate dependencies.

Options:

• -f, --file PATH: Path to pyproject.toml file (default: pyproject.toml)
• --check-duplicates / --no-check-duplicates: Check for duplicate dependencies (default: check)
• --check-missing / --no-check-missing: Check for missing optional dependencies

Examples

Basic Usage

# Convert a single requirements file
depcon convert -r requirements.txt

# Convert with development dependencies
depcon convert -r requirements.txt -d requirements-dev.txt

# Convert with all dependency types
depcon convert \
  -r requirements.txt \
  -d requirements-dev.txt \
  -t requirements-test.txt \
  --docs-requirements requirements-docs.txt

Advanced Usage

# Create a new project with custom metadata
depcon convert \
  -r requirements.txt \
  --project-name "my-project" \
  --project-description "A great Python project" \
  --project-version "1.0.0" \
  --python-version ">=3.12"

# Use different build backend
depcon convert -r requirements.txt --build-backend setuptools

# Append to existing dependencies
depcon convert -r new-requirements.txt --append

# Resolve and pin versions
depcon convert -r requirements.in --resolve

Viewing Dependencies

# Show dependencies in table format
depcon show

# Show in JSON format
depcon show --format json

# Show in YAML format
depcon show --format yaml

Validation

# Validate all dependencies
depcon validate

# Validate specific group
depcon validate --group dev

Exporting Dependencies

# Export main dependencies to requirements.txt
depcon export

# Export specific group
depcon export --group dev -o requirements-dev.txt

# Export all dependencies
depcon export --group all -o requirements-all.txt

Comparing Dependencies

# Show differences between pyproject.toml and requirements.txt
depcon diff -r requirements.txt

# Compare specific group
depcon diff -r requirements-dev.txt --group dev

Syncing Dependencies

# Sync all groups to requirements files
depcon sync

# Sync specific groups
depcon sync --group dev --group test

# Dry run to see what would be synced
depcon sync --dry-run

Generated pyproject.toml Structure

The tool generates modern pyproject.toml files following PEP 621, PEP 639, and PEP 735 standards:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-project"
version = "1.0.0"
description = "A great Python project"
requires-python = ">=3.12"
license = "MIT"
dependencies = [
    "requests>=2.25.0",
    "numpy>=1.20.0",
]

[project.optional-dependencies]
security = [
    "requests[security]>=2.25.0",
]

[dependency-groups]
dev = [
    {include-group = "test"},
    "ruff>=0.1.0",
]
test = [
    "pytest>=7.0.0",
    "pytest-cov>=4.0.0",
]
docs = [
    "sphinx>=5.0.0",
    "sphinx-rtd-theme>=1.0.0",
]

Understanding Dependency Types

• dependencies: Core runtime dependencies required for the package
• [project.optional-dependencies] (PEP 621): Installable extras (e.g., pip install package[security])
• [dependency-groups] (PEP 735): Development dependencies for tools like uv (not installable extras). Supports include-group to compose groups.

Supported File Formats

• requirements.txt - Standard pip requirements files
• requirements.in - pip-tools input files
• requirements-dev.txt - Development dependencies
• requirements-test.txt - Test dependencies
• requirements-docs.txt - Documentation dependencies
• Custom requirement files with any name

Dependency Grouping

The tool intelligently groups dependencies based on common patterns:

• Main Dependencies: Core project dependencies
• Development Dependencies: Tools like pytest, black, ruff, mypy, pre-commit
• Test Dependencies: Testing frameworks and utilities
• Documentation Dependencies: Sphinx, mkdocs, and related tools

Integration with Modern Tools

uv Integration

depcon uses [dependency-groups] (PEP 735) for uv, which is the modern standard:

# Initialize project with uv
uv init

# Convert dependencies
depcon convert -r requirements.txt

# Sync dependencies with uv
uv sync

# Install specific dependency groups
uv sync --group dev --group test

Hatch Integration

# Convert with hatchling backend
depcon convert -r requirements.txt --build-backend hatchling

# Build with hatch
hatch build

Poetry Integration

# Convert with poetry backend
depcon convert -r requirements.txt --build-backend poetry

# Install dependencies
poetry install

Migration Workflow

1. Backup: The tool automatically creates backups of existing pyproject.toml files
2. Convert: Run depcon convert with your requirements files
3. Validate: Use depcon validate to check for issues
4. Review: Examine the generated pyproject.toml file
5. Test: Install dependencies and test your project
6. Cleanup: Remove old requirements files once satisfied

Documentation

Comprehensive documentation is available at https://lancereinsmith.github.io/depcon/.

• Installation Guide - Detailed installation instructions
• Quick Start - Get up and running quickly
• User Guide - Complete feature reference
• API Reference - Detailed API documentation
• Examples - Real-world usage examples
• Contributing - How to contribute to the project
• Changelog - Changelog

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

Quick Development Setup

# Clone the repository
git clone https://github.com/lancereinsmith/depcon.git
cd depcon

# Install in development mode
uv sync

# Install pre-commit hooks
pre-commit install

# Run all checks
make check

License

depcon is licensed under the MIT License. See the LICENSE file for details.