pepscript 0.1.0__py3-none-any.whl

pepscript/__init__.py

@@ -0,0 +1,29 @@
+"""Public API for PEPScript."""
+
+from .config import ToolConfig
+from .exceptions import (
+    DuplicateMetadataBlockError,
+    FileLoadError,
+    MetadataParseError,
+    MetadataValidationError,
+    PEPScriptError,
+    SaveError,
+)
+from .models import ConfigRoot, Metadata, ScriptFileInfo
+from .script import PEPScript, parse_file, parse_script
+
+__all__ = [
+    "ToolConfig",
+    "DuplicateMetadataBlockError",
+    "FileLoadError",
+    "MetadataParseError",
+    "MetadataValidationError",
+    "ConfigRoot",
+    "Metadata",
+    "PEPScript",
+    "PEPScriptError",
+    "SaveError",
+    "ScriptFileInfo",
+    "parse_file",
+    "parse_script",
+]

pepscript/config.py

@@ -0,0 +1,167 @@
+"""Dynamic configuration node for nested tool configuration."""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Iterable, Iterator, Mapping
+from dataclasses import dataclass, field
+from typing import Any, cast, overload
+
+
+def _wrap_value(value: Any) -> Any:
+    if isinstance(value, ToolConfig):
+        return value
+    if isinstance(value, Mapping):
+        return ToolConfig.from_dict(dict(value))
+    if isinstance(value, list):
+        return [_wrap_value(item) for item in value]
+    return value
+
+
+def _unwrap_value(value: Any) -> Any:
+    if isinstance(value, ToolConfig):
+        return value.to_dict()
+    if isinstance(value, list):
+        return [_unwrap_value(item) for item in value]
+    return value
+
+
+@dataclass(slots=True)
+class ToolConfig:
+    """Mapping-like node with attribute and item access."""
+
+    _data: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    def __post_init__(self) -> None:
+        self._data = {key: _wrap_value(value) for key, value in self._data.items()}
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> ToolConfig:
+        """Create a ``ToolConfig`` from a plain mapping, wrapping nested dicts recursively.
+
+        Args:
+            data: A mapping whose values may themselves be mappings, lists, or
+                scalar values.
+
+        Returns:
+            A new ``ToolConfig`` with all nested ``Mapping`` values converted to ``ToolConfig`` instances.
+        """
+        return cls(_data={key: _wrap_value(value) for key, value in data.items()})
+
+    def to_dict(self) -> dict[str, Any]:
+        """Recursively unwrap this node to a plain ``dict``.
+
+        Returns:
+            A plain ``dict`` where all nested ``ToolConfig`` values are also unwrapped to ``dict``.
+        """
+        return {key: _unwrap_value(value) for key, value in self._data.items()}
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Return the value for *key*, or *default* if the key is absent.
+
+        Args:
+            key: The key to look up.
+            default: Value returned when *key* is not present. Defaults to ``None``.
+
+        Returns:
+            The stored value (which may be a ``ToolConfig``) or *default*.
+        """
+        return self._data.get(key, default)
+
+    def setdefault(self, key: str, default: Any = None) -> Any:
+        """Return the value for *key*, inserting *default* if the key is absent.
+
+        Mirrors ``dict.setdefault``. If *default* is a ``Mapping`` it is wrapped
+        in a ``ToolConfig`` before insertion.
+
+        Args:
+            key: The key to look up or insert.
+            default: Value to insert and return when *key* is not present.
+                Defaults to ``None``.
+
+        Returns:
+            The existing value for *key*, or the newly inserted *default*.
+        """
+        value = self._data.setdefault(key, _wrap_value(default))
+        return value
+
+    @overload
+    def update(self, mapping: Mapping[str, Any], /, **kwargs: Any) -> None: ...
+
+    @overload
+    def update(self, mapping: Iterable[tuple[str, Any]], /, **kwargs: Any) -> None: ...
+
+    @overload
+    def update(self, /, **kwargs: Any) -> None: ...
+
+    def update(
+        self,
+        mapping: Mapping[str, Any] | Iterable[tuple[str, Any]] = (),
+        /,
+        **kwargs: Any,
+    ) -> None:
+        """Update the node with key/value pairs, mirroring ``dict.update``.
+
+        Accepts a ``Mapping``, an iterable of ``(key, value)`` pairs, or keyword
+        arguments (or any combination).  Any ``Mapping`` values are wrapped in
+        ``ToolConfig`` instances.
+
+        Args:
+            mapping: A ``Mapping`` or iterable of ``(key, value)`` pairs to merge.
+            **kwargs: Additional key/value pairs to merge.
+        """
+        items: Iterator[tuple[str, Any]]
+        if isinstance(mapping, Mapping):
+            items = iter(cast(Iterable[tuple[str, Any]], mapping.items()))
+        else:
+            items = iter(mapping)
+        for key, value in items:
+            self._data[key] = _wrap_value(value)
+        for key, value in kwargs.items():
+            self._data[key] = _wrap_value(value)
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> ToolConfig:
+        new = object.__new__(type(self))
+        memo[id(self)] = new
+        object.__setattr__(
+            new,
+            "_data",
+            {key: copy.deepcopy(value, memo) for key, value in self._data.items()},
+        )
+        return new
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self._data[name]
+        except KeyError as error:
+            raise AttributeError(name) from error
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name.startswith("_"):
+            object.__setattr__(self, name, value)
+            return
+        self._data[name] = _wrap_value(value)
+
+    def __getitem__(self, key: str) -> Any:
+        return self._data[key]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self._data[key] = _wrap_value(value)
+
+    def __delitem__(self, key: str) -> None:
+        del self._data[key]
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._data
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __bool__(self) -> bool:
+        return bool(self._data)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.to_dict()!r})"

pepscript/exceptions.py

@@ -0,0 +1,27 @@
+"""Custom exceptions for PEPScript."""
+
+from __future__ import annotations
+
+
+class PEPScriptError(Exception):
+    """Base exception for all PEPScript errors."""
+
+
+class FileLoadError(PEPScriptError):
+    """Raised when a script file cannot be read."""
+
+
+class DuplicateMetadataBlockError(PEPScriptError):
+    """Raised when multiple PEP 723 metadata blocks are present."""
+
+
+class MetadataParseError(PEPScriptError):
+    """Raised when metadata cannot be parsed."""
+
+
+class MetadataValidationError(PEPScriptError):
+    """Raised when metadata is structurally invalid."""
+
+
+class SaveError(PEPScriptError):
+    """Raised when a script cannot be saved."""

pepscript/io.py

@@ -0,0 +1,39 @@
+"""File IO helpers for PEPScript."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .exceptions import FileLoadError, SaveError
+from .models import ScriptFileInfo
+
+
+def build_file_info(path: Path, *, encoding: str) -> ScriptFileInfo:
+    """Build typed file info for a script path."""
+
+    return ScriptFileInfo(
+        path=path,
+        name=path.stem,
+        filename=path.name,
+        suffix=path.suffix,
+        exists=path.exists(),
+        encoding=encoding,
+    )
+
+
+def read_source(path: Path, *, encoding: str) -> str:
+    """Read source from disk."""
+
+    try:
+        return path.read_text(encoding=encoding)
+    except OSError as error:
+        raise FileLoadError(f"Failed to read file: {path}") from error
+
+
+def write_source(path: Path, source: str, *, encoding: str) -> None:
+    """Write source to disk."""
+
+    try:
+        path.write_text(source, encoding=encoding)
+    except OSError as error:
+        raise SaveError(f"Failed to write file: {path}") from error

pepscript/models.py

@@ -0,0 +1,87 @@
+"""Typed models for PEPScript."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .config import ToolConfig
+
+
+@dataclass(slots=True)
+class ScriptFileInfo:
+    """Summary of file metadata exposed by PEPScript."""
+
+    path: Path
+    name: str
+    filename: str
+    suffix: str
+    exists: bool
+    encoding: str
+
+
+@dataclass(slots=True)
+class BlockInfo:
+    """Character offsets for a PEP 723 metadata block."""
+
+    start: int
+    end: int
+    content_start: int
+    content_end: int
+    block_type: str
+
+
+@dataclass(slots=True)
+class ConfigRoot:
+    """Root container for metadata configuration."""
+
+    tool: ToolConfig = field(default_factory=ToolConfig)
+
+
+@dataclass(slots=True)
+class Metadata:
+    """Typed metadata model for PEP 723 script metadata."""
+
+    dependencies: list[str] = field(default_factory=list)
+    requires_python: str | None = None
+    config: ConfigRoot = field(default_factory=ConfigRoot)
+
+    def add_dependency(self, dep: str) -> None:
+        """Add a dependency if it is not already present (exact string match).
+
+        Args:
+            dep: A PEP 508 dependency specifier string (e.g. ``"requests>=2.0"``).
+        """
+        if dep not in self.dependencies:
+            self.dependencies.append(dep)
+
+    def remove_dependency(self, dep: str) -> None:
+        """Remove a dependency if present (exact string match, no-op if not found).
+
+        Args:
+            dep: The exact dependency string to remove.
+        """
+        if dep in self.dependencies:
+            self.dependencies.remove(dep)
+
+    def set_requires_python(self, spec: str | None) -> None:
+        """Set or remove the ``requires-python`` field.
+
+        Args:
+            spec: A PEP 440 version specifier string (e.g. ``">=3.12"``), or
+                ``None`` to remove the field from the metadata block.
+        """
+        self.requires_python = spec
+
+    @property
+    def is_empty(self) -> bool:
+        """Return ``True`` if this metadata object holds no meaningful content.
+
+        Used internally to decide whether to write a ``# /// script`` block
+        when the source did not originally contain one.
+        """
+        return (
+            not self.dependencies
+            and self.requires_python is None
+            and not self.config.tool.to_dict()
+        )

pepscript/parser.py

@@ -0,0 +1,161 @@
+"""PEP 723 metadata block detection and parsing."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import tomllib
+from typing import Any, NoReturn, cast
+
+from .config import ToolConfig
+from .exceptions import DuplicateMetadataBlockError, MetadataParseError
+from .models import BlockInfo, ConfigRoot, Metadata
+from .validate import validate_metadata
+
+
+@dataclass(slots=True)
+class ParseResult:
+    """Parsed metadata and optional block offsets."""
+
+    meta: Metadata | None
+    block: BlockInfo | None
+
+
+def _is_start_marker(line: str) -> bool:
+    return line.strip() == "# /// script"
+
+
+def _is_end_marker(line: str) -> bool:
+    return line.strip() == "# ///"
+
+
+def _raise_parse_error(message: str, *, path: Path | None = None) -> NoReturn:
+    if path is None:
+        raise MetadataParseError(message)
+    raise MetadataParseError(f"{message} (path={path})")
+
+
+def _find_blocks(source: str, *, path: Path | None = None) -> list[BlockInfo]:
+    lines = source.splitlines(keepends=True)
+    offsets: list[int] = []
+    total = 0
+    for line in lines:
+        offsets.append(total)
+        total += len(line)
+    offsets.append(total)
+
+    blocks: list[BlockInfo] = []
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        if not _is_start_marker(line):
+            index += 1
+            continue
+
+        end_index = index + 1
+        while end_index < len(lines) and not _is_end_marker(lines[end_index]):
+            end_index += 1
+        if end_index >= len(lines):
+            _raise_parse_error(
+                "Metadata block start marker without end marker", path=path
+            )
+
+        block = BlockInfo(
+            start=offsets[index],
+            end=offsets[end_index + 1],
+            content_start=offsets[index + 1],
+            content_end=offsets[end_index],
+            block_type="script",
+        )
+        blocks.append(block)
+        index = end_index + 1
+
+    return blocks
+
+
+def _extract_toml_content(
+    source: str, block: BlockInfo, *, path: Path | None = None
+) -> str:
+    raw = source[block.content_start : block.content_end]
+    lines = raw.splitlines(keepends=True)
+    content_lines: list[str] = []
+    for line_number, line in enumerate(lines, start=1):
+        if line.strip() == "":
+            _raise_parse_error(
+                f"Invalid metadata content line {line_number}: expected comment-prefixed content",
+                path=path,
+            )
+
+        trimmed = line.lstrip(" \t")
+        if not trimmed.startswith("#"):
+            _raise_parse_error(
+                f"Invalid metadata content line {line_number}: expected '#'",
+                path=path,
+            )
+        text = trimmed[1:]
+        if text.startswith(" "):
+            text = text[1:]
+        content_lines.append(text)
+    return "".join(content_lines)
+
+
+def _parse_metadata_table(
+    table: dict[str, Any], *, path: Path | None = None
+) -> Metadata:
+    dependencies: list[str] = []
+    if "dependencies" in table:
+        value = table["dependencies"]
+        if not isinstance(value, list):
+            _raise_parse_error("'dependencies' must be a list", path=path)
+        for item in cast(list[Any], value):
+            if not isinstance(item, str):
+                _raise_parse_error("'dependencies' entries must be strings", path=path)
+            dependencies.append(item)
+
+    requires_python: str | None = None
+    if "requires-python" in table:
+        value = table["requires-python"]
+        if not isinstance(value, str):
+            _raise_parse_error("'requires-python' must be a string", path=path)
+        requires_python = cast(str, value)
+
+    tool_node = ToolConfig()
+    if "tool" in table:
+        tool = table["tool"]
+        if not isinstance(tool, dict):
+            _raise_parse_error("'tool' must be a table/object", path=path)
+        tool_node = ToolConfig.from_dict(cast(dict[str, Any], tool))
+
+    return Metadata(
+        dependencies=dependencies,
+        requires_python=requires_python,
+        config=ConfigRoot(tool=tool_node),
+    )
+
+
+def parse_source(
+    source: str, *, strict: bool = True, path: Path | None = None
+) -> ParseResult:
+    """Parse PEP 723 metadata from source text."""
+
+    blocks = _find_blocks(source, path=path)
+    if len(blocks) > 1:
+        if path is None:
+            raise DuplicateMetadataBlockError("Multiple PEP 723 metadata blocks found")
+        raise DuplicateMetadataBlockError(
+            f"Multiple PEP 723 metadata blocks found (path={path})"
+        )
+    if not blocks:
+        return ParseResult(meta=None, block=None)
+
+    block = blocks[0]
+    content = _extract_toml_content(source, block, path=path)
+    try:
+        parsed = tomllib.loads(content)
+    except tomllib.TOMLDecodeError as error:
+        _raise_parse_error(f"Invalid metadata TOML: {error}", path=path)
+
+    meta = _parse_metadata_table(parsed, path=path)
+    if strict:
+        validate_metadata(meta, path=path)
+    return ParseResult(meta=meta, block=block)

pepscript/script.py

@@ -0,0 +1,201 @@
+"""Public PEPScript document API."""
+
+from __future__ import annotations
+
+import copy
+from pathlib import Path
+
+from .exceptions import SaveError
+from .io import build_file_info, read_source, write_source
+from .models import BlockInfo, Metadata, ScriptFileInfo
+from .parser import parse_source
+from .serialize import rewrite_source
+from .validate import validate_metadata
+
+
+class PEPScript:
+    """A typed document wrapper for PEP 723-enabled scripts."""
+
+    path: Path | None
+    encoding: str
+    strict: bool
+    source: str
+    file: ScriptFileInfo | None
+    meta: Metadata
+    has_metadata: bool
+    _block: BlockInfo | None
+    _snapshot: tuple[Metadata, BlockInfo | None, bool] | None
+
+    def __init__(
+        self, path: str | Path, *, encoding: str = "utf-8", strict: bool = True
+    ):
+        """Load and parse a PEP 723 script from disk.
+
+        Args:
+            path: Path to the Python script file.
+            encoding: File encoding used when reading and writing. Defaults to ``"utf-8"``.
+            strict: If ``True`` (default), validate metadata immediately after parsing.
+
+        Raises:
+            FileLoadError: If the file cannot be read.
+            DuplicateMetadataBlockError: If more than one ``# /// script`` block is found.
+            MetadataParseError: If the embedded TOML is malformed.
+            MetadataValidationError: If ``strict=True`` and the metadata fails validation.
+        """
+        self.path = Path(path)
+        self.encoding = encoding
+        self.strict = strict
+        self.source = ""
+        self.file = None
+        self.meta = Metadata()
+        self.has_metadata = False
+        self._block = None
+        self._snapshot = None
+        self.reload()
+
+    @classmethod
+    def from_source(cls, source: str, *, strict: bool = True) -> PEPScript:
+        """Create an in-memory script document from source text."""
+
+        instance = cls.__new__(cls)
+        instance.path = None
+        instance.encoding = "utf-8"
+        instance.strict = strict
+        instance.source = source
+        instance.file = None
+        instance.meta = Metadata()
+        instance.has_metadata = False
+        instance._block = None
+        instance._snapshot = None
+        instance._parse_current_source()
+        return instance
+
+    def __enter__(self) -> PEPScript:
+        """Enter edit mode, snapshotting current metadata for potential rollback.
+
+        On a clean exit, changes are automatically persisted via ``save()``
+        (file-backed scripts only; in-memory scripts retain edits in-memory).
+        If an exception propagates out of the ``with`` block, all in-memory
+        edits are discarded by restoring the pre-enter snapshot.
+
+        Only ``meta``, ``has_metadata``, and the internal block offsets are
+        snapshotted — the full source text is not copied — so this is efficient
+        even for large files.
+        """
+        self._snapshot = (copy.deepcopy(self.meta), self._block, self.has_metadata)
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        """Exit edit mode, saving or rolling back depending on whether an exception occurred.
+
+        On clean exit, ``save()`` is called for file-backed scripts.
+        On exception, in-memory state is restored from the snapshot taken at
+        ``__enter__`` and the exception is re-raised.
+        """
+        try:
+            if exc_type is None:
+                if self.path is not None:
+                    self.save()
+            else:
+                if self._snapshot is not None:
+                    self.meta, self._block, self.has_metadata = self._snapshot
+        finally:
+            self._snapshot = None
+        return None
+
+    def _parse_current_source(self) -> None:
+        parsed = parse_source(self.source, strict=self.strict, path=self.path)
+        self.has_metadata = parsed.meta is not None
+        self.meta = parsed.meta if parsed.meta is not None else Metadata()
+        self._block = parsed.block
+
+    def validate(self) -> None:
+        """Run structural validation against the current metadata.
+
+        This is a no-op when the script has no metadata block and ``meta``
+        is empty. Validates:
+
+        - Structural shape of the metadata (correct types for all fields)
+        - Each dependency is a valid PEP 508 specifier (name, extras, version
+          operators, environment markers)
+        - ``requires-python`` is a valid PEP 440 version specifier
+
+        Raises:
+            MetadataValidationError: If the metadata fails structural validation.
+        """
+        if not self.has_metadata and self.meta.is_empty:
+            return
+        validate_metadata(self.meta, path=self.path)
+
+    def reload(self) -> None:
+        """Discard all in-memory edits and reload state from disk (or re-parse source).
+
+        For file-backed scripts (``self.path`` is set), the source is re-read from
+        disk, ``self.file`` is refreshed, and metadata is re-parsed.  For in-memory
+        scripts created via ``from_source``, ``self.source`` is re-parsed without
+        any I/O.
+        """
+        if self.path is None:
+            self._parse_current_source()
+            return
+
+        self.source = read_source(self.path, encoding=self.encoding)
+        self.file = build_file_info(self.path, encoding=self.encoding)
+        self._parse_current_source()
+
+    def to_source(self) -> str:
+        """Serialize current state to source text without writing to disk."""
+        meta_to_write = (
+            self.meta if (self.has_metadata or not self.meta.is_empty) else None
+        )
+        return rewrite_source(self.source, meta=meta_to_write, block=self._block)
+
+    def save(self) -> None:
+        """Persist the current state to disk, then reload.
+
+        The metadata block is deterministically regenerated (keys sorted,
+        consistent formatting) and written back to ``self.path``.  The rest of
+        the source is preserved exactly.  After writing, ``reload()`` is called
+        so that ``self.source``, ``self.file``, and ``self.meta`` reflect the
+        saved file.
+
+        Raises:
+            SaveError: If ``self.path`` is ``None`` (in-memory script) or the
+                file cannot be written.
+        """
+        if self.path is None:
+            raise SaveError("Cannot save in-memory script without a file path")
+        write_source(self.path, self.to_source(), encoding=self.encoding)
+        self.reload()
+
+    def save_as(self, path: str | Path) -> None:
+        """Write the current state to an arbitrary path, then reload from that path.
+
+        After a successful write, ``self.path`` is updated to *path* and
+        ``reload()`` is called so that ``self.source``, ``self.file``, and
+        ``self.meta`` reflect the new file location.
+
+        Args:
+            path: Destination file path (``str`` or ``Path``).
+
+        Raises:
+            SaveError: If the file cannot be written.
+        """
+        target = Path(path)
+        write_source(target, self.to_source(), encoding=self.encoding)
+        self.path = target
+        self.reload()
+
+
+def parse_script(source: str, *, strict: bool = True) -> PEPScript:
+    """Parse source text into an in-memory PEPScript."""
+
+    return PEPScript.from_source(source, strict=strict)
+
+
+def parse_file(
+    path: str | Path, *, encoding: str = "utf-8", strict: bool = True
+) -> PEPScript:
+    """Parse a file path into a PEPScript."""
+
+    return PEPScript(path, encoding=encoding, strict=strict)

pepscript/serialize.py

@@ -0,0 +1,145 @@
+"""Serialization and source rewrite utilities."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import json
+import re
+from typing import Any, cast
+
+from .config import ToolConfig
+from .models import BlockInfo, Metadata
+
+_BARE_KEY_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+_CODING_RE = re.compile(r"^[ \t]*#.*coding[:=][ \t]*[-_.a-zA-Z0-9]+")
+
+
+def _format_key(key: str) -> str:
+    if _BARE_KEY_RE.match(key):
+        return key
+    return json.dumps(key)
+
+
+def _to_plain(value: Any) -> Any:
+    if isinstance(value, ToolConfig):
+        return value.to_dict()
+    if isinstance(value, list):
+        return [_to_plain(item) for item in value]
+    return value
+
+
+def _format_value(value: Any) -> str:
+    value = _to_plain(value)
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return json.dumps(value)
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        return repr(value)
+    if value is None:
+        raise TypeError("None is not a TOML scalar value")
+    if isinstance(value, list):
+        inner = ", ".join(_format_value(item) for item in value)
+        return f"[{inner}]"
+    raise TypeError(f"Unsupported TOML value type: {type(value).__name__}")
+
+
+def _emit_table(path: list[str], mapping: Mapping[str, Any], lines: list[str]) -> None:
+    header = ".".join(_format_key(part) for part in path)
+    lines.append(f"[{header}]")
+
+    scalar_keys: list[str] = []
+    table_keys: list[str] = []
+    for key in sorted(mapping):
+        value = _to_plain(mapping[key])
+        if isinstance(value, Mapping):
+            table_keys.append(key)
+        else:
+            scalar_keys.append(key)
+
+    for key in scalar_keys:
+        value = _to_plain(mapping[key])
+        lines.append(f"{_format_key(key)} = {_format_value(value)}")
+
+    for key in table_keys:
+        if lines and lines[-1] != "":
+            lines.append("")
+        child = _to_plain(mapping[key])
+        if isinstance(child, Mapping):
+            _emit_table([*path, key], cast(Mapping[str, Any], child), lines)
+
+
+def serialize_metadata_toml(meta: Metadata) -> str:
+    """Serialize typed metadata into deterministic TOML."""
+
+    lines: list[str] = []
+    if meta.dependencies:
+        lines.append(f"dependencies = {_format_value(meta.dependencies)}")
+    if meta.requires_python is not None:
+        lines.append(f"requires-python = {_format_value(meta.requires_python)}")
+
+    tool = _to_plain(meta.config.tool)
+    if isinstance(tool, Mapping) and tool:
+        if lines:
+            lines.append("")
+        _emit_table(["tool"], cast(Mapping[str, Any], tool), lines)
+
+    if not lines:
+        return ""
+    return "\n".join(lines) + "\n"
+
+
+def render_metadata_block(meta: Metadata) -> str:
+    """Render a PEP 723 block from metadata."""
+
+    toml = serialize_metadata_toml(meta)
+    output: list[str] = ["# /// script\n"]
+    for line in toml.splitlines():
+        if line:
+            output.append(f"# {line}\n")
+        else:
+            output.append("#\n")
+    output.append("# ///\n")
+    return "".join(output)
+
+
+def _insertion_offset(source: str) -> int:
+    lines = source.splitlines(keepends=True)
+    if not lines:
+        return 0
+    offset = 0
+    index = 0
+    if lines and lines[0].startswith("#!"):
+        offset += len(lines[0])
+        index = 1
+    if index < len(lines) and _CODING_RE.match(lines[index]):
+        offset += len(lines[index])
+    return offset
+
+
+def rewrite_source(
+    source: str,
+    *,
+    meta: Metadata | None,
+    block: BlockInfo | None,
+) -> str:
+    """Rewrite source with inserted/replaced/removed metadata block."""
+
+    if block is not None:
+        if meta is None:
+            return source[: block.start] + source[block.end :]
+        rendered = render_metadata_block(meta)
+        return source[: block.start] + rendered + source[block.end :]
+
+    if meta is None:
+        return source
+
+    rendered = render_metadata_block(meta)
+    insert_at = _insertion_offset(source)
+    before = source[:insert_at]
+    after = source[insert_at:]
+
+    spacer = "\n" if after and not after.startswith("\n") else ""
+    return before + rendered + spacer + after

pepscript/validate.py

@@ -0,0 +1,200 @@
+"""PEP 508 dependency and PEP 440 version specifier validation for parsed metadata."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import NoReturn
+
+from .config import ToolConfig
+from .exceptions import MetadataValidationError
+from .models import Metadata
+
+# PEP 508 distribution name: starts/ends with alphanumeric, may contain ._- in between
+_NAME_RE = re.compile(r"^[A-Za-z0-9]([A-Za-z0-9._-]*[A-Za-z0-9])?$")
+
+# PEP 440 version clause: operator + version string (e.g. ">=1.0", "==1.*")
+_VERSION_CLAUSE_RE = re.compile(
+    r"^\s*(~=|===|==|!=|<=|>=|<|>)\s*[A-Za-z0-9.*+!_-]+\s*$"
+)
+
+# Valid PEP 508 marker variable names
+_VALID_MARKER_VARS = frozenset(
+    {
+        "os_name",
+        "sys_platform",
+        "platform_machine",
+        "platform_python_implementation",
+        "platform_release",
+        "platform_system",
+        "platform_version",
+        "python_version",
+        "python_full_version",
+        "implementation_name",
+        "implementation_version",
+        "extra",
+        # Deprecated setuptools-style dotted names still seen in the wild
+        "os.name",
+        "sys.platform",
+        "platform.version",
+        "platform.machine",
+        "platform.python_implementation",
+    }
+)
+
+_MARKER_KEYWORDS = frozenset({"and", "or", "not", "in"})
+
+# Matches simple and dotted identifiers (e.g. python_version, os.name)
+_MARKER_IDENT_RE = re.compile(r"\b([a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*)\b")
+
+
+def _raise_validation_error(message: str, *, path: Path | None = None) -> NoReturn:
+    if path is None:
+        raise MetadataValidationError(message)
+    raise MetadataValidationError(f"{message} (path={path})")
+
+
+def _is_scalar(value: object) -> bool:
+    return isinstance(value, (str, int, float, bool))
+
+
+def _validate_tool_value(
+    value: object, *, path: Path | None = None, location: str = "tool"
+) -> None:
+    if isinstance(value, ToolConfig):
+        _validate_tool_value(value.to_dict(), path=path, location=location)
+        return
+    if isinstance(value, Mapping):
+        for key, item in value.items():
+            if not isinstance(key, str):
+                _raise_validation_error(f"{location} keys must be strings", path=path)
+            _validate_tool_value(item, path=path, location=f"{location}.{key}")
+        return
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            _validate_tool_value(item, path=path, location=f"{location}[{index}]")
+        return
+    if _is_scalar(value):
+        return
+    _raise_validation_error(
+        f"{location} contains unsupported value type: {type(value).__name__}", path=path
+    )
+
+
+def _validate_marker(marker: str, *, loc: str, path: Path | None = None) -> None:
+    """Check that all unquoted identifiers in a marker expression are valid."""
+    without_quotes = re.sub(r'"[^"]*"|\'[^\']*\'', "", marker)
+    for match in _MARKER_IDENT_RE.finditer(without_quotes):
+        ident = match.group(1)
+        if ident in _MARKER_KEYWORDS:
+            continue
+        if ident not in _VALID_MARKER_VARS:
+            _raise_validation_error(
+                f"{loc} has unknown marker variable {ident!r}", path=path
+            )
+
+
+def _validate_pep508_dependency(
+    dep: str, *, path: Path | None = None, index: int = 0
+) -> None:
+    """Validate a single PEP 508 dependency specifier string."""
+    loc = f"dependencies[{index}]"
+    raw = dep.strip()
+
+    if not raw:
+        _raise_validation_error(f"{loc} must not be empty", path=path)
+
+    # Split off environment marker at first semicolon
+    if ";" in raw:
+        req_part, marker_part = raw.split(";", 1)
+        _validate_marker(marker_part.strip(), loc=loc, path=path)
+    else:
+        req_part = raw
+
+    req_part = req_part.strip()
+    is_url = "@" in req_part
+
+    # For URL requirements validate only the name/extras part before the @
+    name_scope = req_part[: req_part.index("@")].strip() if is_url else req_part
+
+    # Extract package name (stops at [, version operator chars, whitespace, or end)
+    name_match = re.match(r"[A-Za-z0-9][A-Za-z0-9._-]*", name_scope)
+    if not name_match:
+        _raise_validation_error(
+            f"{loc} has an invalid package name in {dep!r}", path=path
+        )
+
+    name = name_match.group()
+    if not _NAME_RE.match(name):
+        _raise_validation_error(f"{loc} has invalid package name {name!r}", path=path)
+
+    rest = name_scope[name_match.end() :].strip()
+
+    # Optional extras: [extra1, extra2, ...]
+    if rest.startswith("["):
+        close = rest.find("]")
+        if close == -1:
+            _raise_validation_error(
+                f"{loc} has unclosed extras '[' in {dep!r}", path=path
+            )
+        for extra in rest[1:close].split(","):
+            e = extra.strip()
+            if not e:
+                continue
+            if not _NAME_RE.match(e):
+                _raise_validation_error(f"{loc} has invalid extra {e!r}", path=path)
+        rest = rest[close + 1 :].strip()
+
+    # For URL requirements, nothing should remain between name/extras and @
+    if is_url and rest:
+        _raise_validation_error(
+            f"{loc} has unexpected content before '@' in {dep!r}", path=path
+        )
+
+    # Version specifiers (not applicable for URL requirements)
+    if not is_url and rest:
+        for clause in rest.split(","):
+            if not _VERSION_CLAUSE_RE.match(clause):
+                _raise_validation_error(
+                    f"{loc} has invalid version specifier {clause.strip()!r} in {dep!r}",
+                    path=path,
+                )
+
+
+def _validate_requires_python(spec: str, *, path: Path | None = None) -> None:
+    """Validate a PEP 440 requires-python version specifier string."""
+    for clause in spec.split(","):
+        if not _VERSION_CLAUSE_RE.match(clause):
+            _raise_validation_error(
+                f"'requires-python' has invalid specifier {clause.strip()!r}",
+                path=path,
+            )
+
+
+def validate_metadata(meta: Metadata | None, *, path: Path | None = None) -> None:
+    """Validate metadata structure, PEP 508 dependency specifiers, and PEP 440 version constraints."""
+
+    if meta is None:
+        return
+
+    if not isinstance(meta.dependencies, list):
+        _raise_validation_error("'dependencies' must be a list", path=path)
+    for index, dep in enumerate(meta.dependencies):
+        if not isinstance(dep, str):
+            _raise_validation_error(
+                f"'dependencies[{index}]' must be a string",
+                path=path,
+            )
+        else:
+            _validate_pep508_dependency(dep, path=path, index=index)
+
+    if meta.requires_python is not None:
+        if not isinstance(meta.requires_python, str):
+            _raise_validation_error(
+                "'requires-python' must be a string or None", path=path
+            )
+        else:
+            _validate_requires_python(meta.requires_python, path=path)
+
+    _validate_tool_value(meta.config.tool, path=path)

pepscript-0.1.0.dist-info/METADATA

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: pepscript
+Version: 0.1.0
+Summary: Typed Python library for working with PEP 723 inline script metadata
+Keywords: pep723,metadata,inline-script,toml
+Author: maximiliancw
+Author-email: maximiliancw <wunderkind.serie-0f@icloud.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/botlot-project/PEPscript
+Description-Content-Type: text/markdown
+
+# PEPScript
+
+[![CI](https://github.com/botlot-project/PEPscript/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/botlot-project/PEPscript/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pepscript)](https://pypi.org/project/pepscript/)
+[![Python](https://img.shields.io/pypi/pyversions/pepscript)](https://pypi.org/project/pepscript/)
+[![License](https://img.shields.io/pypi/l/pepscript)](https://github.com/botlot-project/PEPscript/blob/main/LICENSE)
+[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/botlot-project/PEPscript)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://botlot-project.github.io/PEPscript/)
+
+A Python library for parsing, validating, editing, and saving [PEP 723](https://peps.python.org/pep-0723/) inline script metadata through a typed API.
+
+- Zero runtime dependencies (stdlib only)
+- Python 3.12+
+- Full type hints with `py.typed`
+
+## Installation
+
+```bash
+pip install pepscript
+```
+
+## Usage
+
+### Read metadata from a script
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```bash
+uv sync
+```
+
+### Running checks
+
+```bash
+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](https://semver.org/). The version is set in `pyproject.toml`.
+
+To release:
+
+1. Update `version` in `pyproject.toml`
+2. Tag and push:
+   ```bash
+   git tag v0.2.0
+   git push --tags
+   ```
+
+Commit messages should follow [Conventional Commits](https://www.conventionalcommits.org/) (`fix:`, `feat:`, `feat!:` for breaking changes).
+
+## License
+
+MIT

pepscript-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pepscript/__init__.py,sha256=n4fZdoVoHITLmVGJeLltD5pkyJToivZnddiblL5ikm0,641
+pepscript/config.py,sha256=GjBOT0bapLN2SKKT20sY7U06qMEicRBclzfIwV_H8Ss,5489
+pepscript/exceptions.py,sha256=wnRj1en3Jk-sqpVJQQxhh6JclHQ8V7HuupGIejhcFx4,654
+pepscript/io.py,sha256=W8LLz0Z7PZkWTGhkWx3t22tVok1D46VTOKUlGK1XUtQ,1005
+pepscript/models.py,sha256=pWCQT0vzOM12oSgi9Un0OlMx9TW8LeBHOS5WAK0ofgU,2349
+pepscript/parser.py,sha256=DxGFlRwof1JPU9RaB_RjEvrmNTvkqefpPqCS8wBfZwc,5023
+pepscript/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pepscript/script.py,sha256=i71cmKtecNHDdCm54vgmiCL4bdKSuthHA-90fcQfszI,7484
+pepscript/serialize.py,sha256=XClSbYNu8vknutL4-13Rf31NVTjmv6RpCoODlVNlgx8,4221
+pepscript/validate.py,sha256=IlPFCJeIntdaNPem4J6KGZz8WCZdRjrgfyu3ExMJryY,7028
+pepscript-0.1.0.dist-info/WHEEL,sha256=Sb1dMJuf3wy6TqB8bzcqZpk8WSKCV8HbGz39HaP5dwE,81
+pepscript-0.1.0.dist-info/METADATA,sha256=1Mhe3IZaP22lSBXHTZczUgx-qQOS1TG9PSmW2k5h3-c,3595
+pepscript-0.1.0.dist-info/RECORD,,

pepscript-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.10.10
+Root-Is-Purelib: true
+Tag: py3-none-any