How It Works

This section explains the internal mechanics of autopep723 and how the different execution modes function.

Overview

autopep723 analyzes Python scripts using Abstract Syntax Tree (AST) parsing to detect third-party imports, then either generates PEP 723 metadata or executes the script with automatic dependency management.

Execution Flow

        flowchart TD
    A[User runs: uvx autopep723 script.py] --> B{uvx available?}
    B -->|No| C[Error: Install uv]
    B -->|Yes| D[uvx creates ephemeral venv]
    D --> E[uvx installs autopep723 in venv]
    E --> F[autopep723 starts execution]
    F --> G{Script exists?}
    G -->|No| H[Error: File not found]
    G -->|Yes| I[Read script content]
    I --> J{Has PEP 723 metadata?}
    J -->|Yes| K[Extract existing dependencies]
    J -->|No| L[Parse with AST]
    L --> M[Extract import statements]
    M --> N[Filter stdlib modules]
    N --> O[Map import names to packages]
    O --> P[Generate dependency list]
    K --> Q[uv run --with deps script.py]
    P --> Q
    Q --> R[Script executes with dependencies]
    R --> S[Clean up ephemeral venv]

Mode-Specific Behavior

Run Mode (Default)

When you execute autopep723 script.py:

  1. Script Analysis: Parses the Python file using AST

  2. Dependency Detection: Identifies third-party imports

  3. Execution: Runs uv run --with <deps> script.py

Check Mode

When you execute autopep723 check script.py:

  1. Script Analysis: Same parsing process

  2. Metadata Generation: Creates PEP 723 format

  3. Output: Prints metadata to stdout (no execution)

Add Mode

When you execute autopep723 add script.py:

  1. Script Analysis: Same parsing process

  2. File Modification: Adds metadata block to top of file

  3. Safety Check: Skips if metadata already exists

The add command is analogous to uv add --script script.py 'dep1' 'dep2', but with automatic dependency detection - you don’t need to manually specify which packages to add.

Import Analysis Process

        flowchart LR
    A[Python Script] --> B[AST Parser]
    B --> C[Extract Imports]
    C --> D{Import Type}
    D -->|import module| E[Direct Import]
    D -->|from module import| F[From Import]
    E --> G[Module Name]
    F --> G
    G --> H{Standard Library?}
    H -->|Yes| I[Skip]
    H -->|No| J{In Mapping Table?}
    J -->|Yes| K[Use Mapped Name]
    J -->|No| L[Use Original Name]
    K --> M[Final Package List]
    L --> M
    I --> N[End]

Import Name Mapping

The tool maintains a mapping table for packages where the import name differs from the package name:

# Examples from the mapping table
"bs4": "beautifulsoup4",
"PIL": "Pillow", 
"cv2": "opencv-python",
"sklearn": "scikit-learn"

This handles the common discrepancy between pip install package-name and import module_name.

uvx Integration

What uvx Does

When you run uvx autopep723:

  1. Environment Creation: Creates a temporary virtual environment

  2. Tool Installation: Installs autopep723 and its dependencies (rich)

  3. Execution: Runs the tool in the isolated environment

  4. Cleanup: Removes the environment after execution

Why This Works

  • ✅ No system pollution: Tools don’t interfere with system Python

  • ✅ Dependency isolation: Each execution is clean

  • ✅ Always fresh: Latest version of the tool

  • ✅ No conflicts: No dependency version conflicts

Shebang Mechanics

Unix/Linux/macOS

The shebang #!/usr/bin/env -S uvx autopep723 works by:

  1. Shell interpretation: Shell reads the shebang line

  2. Command execution: Runs uvx autopep723 script.py

  3. File as argument: The script file becomes the argument

Note: The -S flag is required for env to properly handle arguments with spaces. This flag is available in most modern Unix systems (GNU coreutils 8.30+, macOS 10.15+). For older systems, consider using permanent installation with uv tool install autopep723 and the simpler shebang #!/usr/bin/env autopep723.

Windows Compatibility

Traditional shebangs don’t work on Windows, but there are alternatives:

Option 1: Python Launcher (py.exe)

Windows Python installations include py.exe which can handle shebangs:

#!python
# /// script
# dependencies = ["requests"]
# ///
import subprocess
import sys

# Run through autopep723
subprocess.run([sys.executable, "-m", "uvx", "autopep723", __file__])

Option 2: Batch File Wrapper

Create script.bat:

@echo off
uvx autopep723 %~dp0script.py

Option 3: PowerShell Script

Create script.ps1:

uvx autopep723 "$PSScriptRoot\script.py"

Best Practice for Cross-Platform

For maximum compatibility, use explicit execution rather than shebangs:

# Unix/Linux/macOS
uvx autopep723 script.py

# Windows (same command)
uvx autopep723 script.py

Error Handling Flow

        flowchart TD
    A[Start] --> B{File exists?}
    B -->|No| C[FileNotFoundError]
    B -->|Yes| D{Valid Python syntax?}
    D -->|No| E[Return empty deps]
    D -->|Yes| F{uv available?}
    F -->|No| G[Installation error]
    F -->|Yes| H[Process normally]
    C --> I[Exit code 1]
    E --> J[Continue with empty list]
    G --> K[Exit code 2]
    H --> L[Success]

Performance Characteristics

Analysis Speed

  • AST parsing: ~1-5ms for typical scripts

  • Import detection: Linear with number of imports

  • No network calls: All analysis is local and fast

Memory Footprint

  • Minimal usage: Processes one script at a time

  • No persistent state: Each run is independent

  • Clean execution: No background processes

Caching Strategy

  • No caching: Each execution analyzes fresh

  • Intentional design: Ensures accuracy over speed

  • Fast enough: Analysis is already very fast

Integration Points

With uv

autopep723 leverages uv’s capabilities:

  • Fast dependency resolution

  • Isolated execution environments

  • Cross-platform compatibility

With PEP 723

Generates compliant metadata:

  • Proper TOML format in comments

  • Standard field names (requires-python, dependencies)

  • Tool-agnostic specification

With Python Ecosystem

Works with standard tools:

  • AST module for parsing

  • Standard library for most functionality

  • Minimal external dependencies