flowchart TD
    Start([Need Python CLI script]) --> Q1{Environment allows network access<br>for dependency installation?}
    Q1 -->|Yes — standard environment| UseTyper[Use python-cli-architect with Typer+Rich<br>Less code, better UX, well-tested libraries]
    Q1 -->|No — restricted environment| Q2{Restriction type confirmed?}
    Q2 -->|No — assumption only| Stop[STOP — Verify with user first<br>Do not assume restrictions]
    Q2 -->|Yes — airgapped/no internet/no uv| StdLib[Use stdlib-scripting<br>Maximum portability, basic UX]

    UseTyper --> Why1[Why: PEP 723 + uv handles dependencies<br>Simpler code, richer features]
    StdLib --> Why2[Why: Runs anywhere Python 3.11+ installed<br>More code to write and maintain]

REFACTORING IMPACT ANALYSIS:
- Line count: X -> Y (∆ Z)
- Functions affected: N
- Patterns applied: [...]
- Complexity reduction: [...]
- Rejected changes: [reasons]

python -m py_compile <file>
grep -E "from typing import .*(Dict|List|Set|Tuple|Optional|Union)\b" <file>
ruff check <file>
# Type check: match the host project — ty is default in this repo (`uv run ty check <file>`);
# use `mypy --strict <file>` when the project standardizes on mypy or uv is unavailable.

VALIDATION REPORT:
✅ Syntax check: PASSED
✅ Forbidden patterns: NONE FOUND
✅ Native type hints: VERIFIED (X instances)
✅ Ruff: PASSED
✅ Type check (ty or mypy): PASSED
✅ Checklist items: COMPLETED

from shutil import which
import os, subprocess

def run_privileged_command(cmd: str, args: list[str]) -> subprocess.CompletedProcess[str]:
    if os.name != "posix":
        return subprocess.run([cmd, *args], capture_output=True, text=True)
    if os.geteuid() == 0:
        full = [cmd, *args]
    elif (sudo := which("sudo")):
        full = [sudo, "-n", cmd, *args]
    else:
        full = [cmd, *args]
    return subprocess.run(full, capture_output=True, text=True, check=False)

import argparse

def create_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="Tool description",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    return parser

import logging
from pathlib import Path

def setup_logging(level: str = "INFO", log_file: Path | None = None) -> None:
    handlers: list[logging.Handler] = [logging.StreamHandler()]
    if log_file:
        handlers.append(logging.FileHandler(log_file))
    logging.basicConfig(
        level=getattr(logging, level.upper(), logging.INFO),
        format="%(asctime)s %(name)s %(levelname)s %(message)s",
        handlers=handlers,
    )

import json, configparser, tomllib
from pathlib import Path
from typing import Any

def load_config(path: Path) -> dict[str, Any]:
    ext = path.suffix.lower()
    data = path.read_text()
    if ext == ".json":
        return json.loads(data)
    if ext == ".toml":
        return tomllib.loads(data)
    if ext in (".ini", ".cfg"):
        p = configparser.ConfigParser()
        p.read_string(data)
        return {sec: dict(p[sec]) for sec in p.sections()}
    raise ValueError(f"Unsupported config format: {ext}")

import logging, sys

class ScriptError(Exception):
    """Base error for script-related failures."""

def handle_error(err: Exception, logger: logging.Logger) -> None:
    logger.error(f"Error: {err}")
    if logger.isEnabledFor(logging.DEBUG):
        logger.exception("Traceback")
    sys.exit(1)

import asyncio
from collections.abc import Coroutine
from typing import Any

async def run_async(tasks: list[Coroutine[Any, Any, Any]]) -> list[Any]:
    return await asyncio.gather(*tasks, return_exceptions=True)

project_name/
├── main.py
├── core/
│   ├── __init__.py
│   ├── config.py
│   ├── logging_setup.py
│   └── exceptions.py
├── utils/
│   ├── __init__.py
│   └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── test_main.py
│   └── test_core.py
├── config.example.toml
└── README.md

import json
from pathlib import Path
from module import load_config

def test_load_json(tmp_path: Path) -> None:
    path = tmp_path / "c.json"
    path.write_text(json.dumps({"k": "v"}))
    result = load_config(path)
    assert result == {"k": "v"}

/python3-development:shebangpython <file_path>