PEPScript

A Python library for parsing, validating, editing, and saving PEP 723 inline script metadata through a typed API.

• Zero runtime dependencies (stdlib only)
• Python 3.12+
• Full type hints with py.typed

Installation

pip install pepscript

Usage

Read metadata from a script

from pepscript import PEPScript

script = PEPScript("my_script.py")
if script.has_metadata:
    print(script.meta.dependencies)
    print(script.meta.requires_python)

Edit and save

from pepscript import PEPScript

with PEPScript("my_script.py") as script:
    script.meta.add_dependency("httpx>=0.27")
    script.meta.set_requires_python(">=3.12")

Parse from a string

from pepscript import parse_script

script = parse_script("""\
# /// script
# dependencies = ["requests>=2.0"]
# requires-python = ">=3.12"
# ///
print("hello")
""")
print(script.meta.dependencies)  # ['requests>=2.0']

Access tool configuration

from pepscript import PEPScript

script = PEPScript("my_script.py")
if script.has_metadata:
    # Attribute access
    ruff = script.meta.config.tool.ruff
    # Item access (for keys with hyphens)
    line_length = ruff["line-length"]
    setting = script.meta.config.tool["my-tool"]["some-setting"]

Validate metadata

from pepscript import PEPScript, MetadataValidationError

script = PEPScript("my_script.py", strict=False)
try:
    script.validate()
except MetadataValidationError as e:
    print(f"Invalid metadata: {e}")

Contributing

Setup

uv sync

Running checks

uv run pytest              # Tests
uv run ruff check .        # Lint
uv run ruff format .       # Format
uv run ty check .          # Type check

Versioning and releases

This project uses Semantic Versioning. The version is set in pyproject.toml. Release notes are generated automatically from Conventional Commits when a version tag is pushed.

To release:

1. Update version in pyproject.toml
2. Push your changes and merge them into main
3. Wait for the CI workflow on main to pass
4. Tag the merged commit on main and push the tag:

   git checkout main
   git pull origin main
   git tag v0.1.2
   git push origin v0.1.2
   

Pushing the tag triggers the release workflow, which builds the package, publishes it to PyPI, generates release notes with git-cliff, and creates the GitHub release.

Commit messages should follow Conventional Commits (fix:, feat:, feat!: for breaking changes).

License

MIT