Examples

This section demonstrates autopep723 usage with real examples from the project.

Simple Demo (No Dependencies)

A basic script that uses only built-in Python modules:

#!/usr/bin/env python3

import json
import os
import sys
from datetime import datetime
from pathlib import Path


def main():
    """Simple demo script that works without external dependencies."""

    print("🎯 autopep723 Demo Script")
    print("=" * 40)

    # Show system info
    print(f"Python version: {sys.version}")
    print(f"Current directory: {os.getcwd()}")
    print(f"Script path: {Path(__file__).absolute()}")
    print(f"Current time: {datetime.now().isoformat()}")

    # Create some sample data
    data = {
        "demo": "autopep723",
        "timestamp": datetime.now().isoformat(),
        "python_version": sys.version_info[:3],
        "features": [
            "Automatic dependency detection",
            "PEP 723 metadata generation",
            "Import name mapping",
            "File update capability",
            "Direct script execution",
        ],
    }

    # Display the data
    print("\n📊 Demo Data:")
    print(json.dumps(data, indent=2))

    # Test some built-in module functionality
    print("\n🔧 Testing built-in modules:")

    # Test pathlib
    current_file = Path(__file__)
    print(f"✓ pathlib: {current_file.name} ({current_file.stat().st_size} bytes)")

    # Test json
    json_str = json.dumps({"test": "data"})
    print(f"✓ json: Serialized {len(json_str)} characters")

    # Test datetime
    now = datetime.now()
    print(f"✓ datetime: {now.strftime('%Y-%m-%d %H:%M:%S')}")

    # Test os
    env_count = len(os.environ)
    print(f"✓ os: Found {env_count} environment variables")

    print("\n✅ All tests completed successfully!")
    print("\nThis script demonstrates autopep723 with a script that:")
    print("  - Uses only built-in Python modules")
    print("  - Should generate empty dependencies list")
    print("  - Can be run without any external packages")
    print("\nTry running:")
    print("  autopep723 examples/simple_demo.py")
    print("  autopep723 add examples/simple_demo.py")
    print("  autopep723 check examples/simple_demo.py")


if __name__ == "__main__":
    main()

Usage:

# Check what dependencies would be detected (should be empty)
autopep723 check examples/simple_demo.py

# Run the script
autopep723 examples/simple_demo.py

Web Scraper

A script that uses external packages (requests and beautifulsoup4):

#!/usr/bin/env python3

import json
import time
from urllib.parse import urljoin

import requests
from bs4 import BeautifulSoup


def scrape_website(url):
    """Simple web scraper example using requests and BeautifulSoup."""

    # Make request with headers to avoid being blocked
    headers = {"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"}

    try:
        response = requests.get(url, headers=headers, timeout=10)
        response.raise_for_status()

        # Parse HTML content
        soup = BeautifulSoup(response.content, "html.parser")

        # Extract basic information
        title = soup.find("title")
        title_text = title.get_text().strip() if title else "No title found"

        # Find all links
        links = []
        for link in soup.find_all("a", href=True):
            href = link["href"]
            absolute_url = urljoin(url, href)
            link_text = link.get_text().strip()
            if link_text:
                links.append({"url": absolute_url, "text": link_text})

        # Extract meta description
        meta_desc = soup.find("meta", attrs={"name": "description"})
        description = meta_desc.get("content", "") if meta_desc else ""

        return {
            "url": url,
            "title": title_text,
            "description": description,
            "links_count": len(links),
            "links": links[:10],  # First 10 links only
            "scraped_at": time.time(),
        }

    except requests.RequestException as e:
        print(f"Error scraping {url}: {e}")
        return None


def main():
    """Main function to demonstrate the scraper."""

    # Example URLs to scrape
    urls = [
        "https://httpbin.org/html",
        "https://example.com",
    ]

    results = []

    for url in urls:
        print(f"Scraping: {url}")
        result = scrape_website(url)

        if result:
            results.append(result)
            print(f"✓ Title: {result['title']}")
            print(f"✓ Links found: {result['links_count']}")
        else:
            print("✗ Failed to scrape")

        # Be polite to servers
        time.sleep(1)

    # Save results to JSON file
    with open("scrape_results.json", "w") as f:
        json.dump(results, f, indent=2)

    print("\nScraping complete! Results saved to scrape_results.json")
    print(f"Total sites scraped: {len(results)}")


if __name__ == "__main__":
    main()

Usage:

# Check detected dependencies
autopep723 check examples/web_scraper.py

# Update file with PEP 723 metadata
autopep723 add examples/web_scraper.py

# Run with automatic dependency management
autopep723 examples/web_scraper.py

Expected dependencies:

• requests - HTTP library

• beautifulsoup4 - HTML parsing (from bs4 import)

Shebang Example

Demonstrates using autopep723 as a shebang for executable scripts:

#!/usr/bin/env autopep723
import json
from datetime import datetime

import requests


def main():
    """Example script that demonstrates shebang usage with autopep723."""

    print("🚀 Shebang Example Script")
    print("=" * 40)
    print("This script demonstrates using autopep723 as a shebang!")
    print()

    # Make a simple HTTP request
    try:
        print("📡 Making HTTP request to httpbin.org...")
        response = requests.get("https://httpbin.org/json", timeout=10)
        response.raise_for_status()

        data = response.json()
        print("✅ Request successful!")
        print(f"Response data: {json.dumps(data, indent=2)}")

    except requests.RequestException as e:
        print(f"❌ Request failed: {e}")
        return 1

    print()
    print("🎯 Key Points:")
    print("  - This script uses '#!/usr/bin/env autopep723' as shebang")
    print("  - autopep723 automatically detected 'requests' dependency")
    print("  - The script runs with: uv run --with requests script.py")
    print("  - No need to manually declare PEP 723 metadata!")

    print()
    print(f"⏰ Executed at: {datetime.now().isoformat()}")

    return 0


if __name__ == "__main__":
    exit(main())

Usage:

# Make executable and run directly
chmod +x examples/shebang_example.py
./examples/shebang_example.py

The shebang #!/usr/bin/env autopep723 automatically:

1. Detects the requests dependency

2. Creates an isolated environment

3. Installs required packages

4. Executes the script

For uvx usage, change the shebang to:

#!/usr/bin/env -S uvx autopep723

Machine Learning Analysis

A comprehensive data science script with multiple dependencies:

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.13"
# dependencies = [
#     "matplotlib",
#     "pandas",
#     "scikit-learn",
#     "seaborn",
# ]
# ///


import matplotlib.pyplot as plt
import pandas as pd
import seaborn as sns
from sklearn.datasets import make_classification
from sklearn.ensemble import RandomForestClassifier
from sklearn.metrics import classification_report, confusion_matrix
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler

This example already includes PEP 723 metadata and demonstrates:

• Data generation and exploration

• Visualization with matplotlib/seaborn

• Machine learning with scikit-learn

• Data manipulation with pandas

Usage:

# Run the complete analysis
autopep723 examples/ml_analysis.py

Dependencies included:

• matplotlib - Plotting library

• pandas - Data manipulation

• scikit-learn - Machine learning (from sklearn import)

• seaborn - Statistical visualization

Import Name Mappings

These examples showcase how autopep723 handles import name mappings:

Script Import	Detected Package	Reason
from bs4 import BeautifulSoup	beautifulsoup4	Import name differs from package
from sklearn import datasets	scikit-learn	Common alias mapping
import requests	requests	Direct mapping
import matplotlib.pyplot	matplotlib	Top-level package detection

Testing the Examples

Run all examples to see autopep723 in action:

# Check all examples
for script in examples/*.py; do
    echo "=== $script ==="
    autopep723 check "$script"
    echo
done

# Run all examples (be patient with ML example!)
for script in examples/*.py; do
    echo "Running $script..."
    autopep723 "$script"
done

Creating Your Own Scripts

Based on these examples, follow this pattern:

1. Write your script with normal import statements

2. Test detection: autopep723 check script.py

3. Add metadata: autopep723 add script.py

4. Make executable (optional): Add shebang and chmod +x

The tool handles the complexity of dependency management automatically!