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
    line_length = script.meta.config.tool.ruff.line_length
    # Item access (for keys with hyphens)
    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. Tag and push:

   git tag v0.1.1
   git push origin v0.1.1

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

License

MIT