pepscript 0.1.0__tar.gz → 0.1.2__tar.gz

{pepscript-0.1.0 → pepscript-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pepscript
-Version: 0.1.0
+Version: 0.1.2
 Summary: Typed Python library for working with PEP 723 inline script metadata
 Keywords: pep723,metadata,inline-script,toml
 Author: maximiliancw
@@ -14,6 +14,8 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Project-URL: Repository, https://github.com/botlot-project/PEPscript
+Project-URL: Documentation, https://botlot-project.github.io/PEPscript/
+Project-URL: Issues, https://github.com/botlot-project/PEPscript/issues
 Description-Content-Type: text/markdown
 
 # PEPScript
@@ -83,8 +85,9 @@ from pepscript import PEPScript
 script = PEPScript("my_script.py")
 if script.has_metadata:
     # Attribute access
-    line_length = script.meta.config.tool.ruff.line_length
+    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"]
 ```
 
@@ -120,16 +123,23 @@ uv run ty check .          # Type check
 ### Versioning and releases
 
 This project uses [Semantic Versioning](https://semver.org/). The version is set in `pyproject.toml`.
+Release notes are generated automatically from [Conventional Commits](https://www.conventionalcommits.org/) when a version tag is pushed.
 
 To release:
 
 1. Update `version` in `pyproject.toml`
-2. Tag and push:
+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:
    ```bash
-   git tag v0.2.0
-   git push --tags
+   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](https://www.conventionalcommits.org/) (`fix:`, `feat:`, `feat!:` for breaking changes).
 
 ## License

{pepscript-0.1.0 → pepscript-0.1.2}/README.md

@@ -65,8 +65,9 @@ from pepscript import PEPScript
 script = PEPScript("my_script.py")
 if script.has_metadata:
     # Attribute access
-    line_length = script.meta.config.tool.ruff.line_length
+    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"]
 ```
 
@@ -102,16 +103,23 @@ uv run ty check .          # Type check
 ### Versioning and releases
 
 This project uses [Semantic Versioning](https://semver.org/). The version is set in `pyproject.toml`.
+Release notes are generated automatically from [Conventional Commits](https://www.conventionalcommits.org/) when a version tag is pushed.
 
 To release:
 
 1. Update `version` in `pyproject.toml`
-2. Tag and push:
+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:
    ```bash
-   git tag v0.2.0
-   git push --tags
+   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](https://www.conventionalcommits.org/) (`fix:`, `feat:`, `feat!:` for breaking changes).
 
 ## License

{pepscript-0.1.0 → pepscript-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pepscript"
-version = "0.1.0"
+version = "0.1.2"
 description = "Typed Python library for working with PEP 723 inline script metadata"
 readme = "README.md"
 license = "MIT"
@@ -21,6 +21,8 @@ classifiers = [
 
 [project.urls]
 Repository = "https://github.com/botlot-project/PEPscript"
+Documentation = "https://botlot-project.github.io/PEPscript/"
+Issues = "https://github.com/botlot-project/PEPscript/issues"
 
 [dependency-groups]
 dev = [

{pepscript-0.1.0 → pepscript-0.1.2}/src/pepscript/io.py

@@ -25,7 +25,8 @@ def read_source(path: Path, *, encoding: str) -> str:
     """Read source from disk."""
 
     try:
-        return path.read_text(encoding=encoding)
+        with path.open("r", encoding=encoding, newline="") as handle:
+            return handle.read()
     except OSError as error:
         raise FileLoadError(f"Failed to read file: {path}") from error
 
@@ -34,6 +35,7 @@ def write_source(path: Path, source: str, *, encoding: str) -> None:
     """Write source to disk."""
 
     try:
-        path.write_text(source, encoding=encoding)
+        with path.open("w", encoding=encoding, newline="") as handle:
+            handle.write(source)
     except OSError as error:
         raise SaveError(f"Failed to write file: {path}") from error

{pepscript-0.1.0 → pepscript-0.1.2}/src/pepscript/models.py

@@ -2,12 +2,23 @@
 
 from __future__ import annotations
 
+from collections.abc import Mapping
 from dataclasses import dataclass, field
 from pathlib import Path
+from typing import Any
 
 from .config import ToolConfig
 
 
+def _mapping_is_deep_empty(value: Mapping[str, Any]) -> bool:
+    if not value:
+        return True
+    return all(
+        isinstance(item, Mapping) and _mapping_is_deep_empty(item)
+        for item in value.values()
+    )
+
+
 @dataclass(slots=True)
 class ScriptFileInfo:
     """Summary of file metadata exposed by PEPScript."""
@@ -83,5 +94,5 @@ class Metadata:
         return (
             not self.dependencies
             and self.requires_python is None
-            and not self.config.tool.to_dict()
+            and _mapping_is_deep_empty(self.config.tool.to_dict())
         )

{pepscript-0.1.0 → pepscript-0.1.2}/src/pepscript/parser.py

@@ -22,11 +22,18 @@ class ParseResult:
 
 
 def _is_start_marker(line: str) -> bool:
-    return line.strip() == "# /// script"
+    return line.rstrip("\r\n") == "# /// script"
 
 
 def _is_end_marker(line: str) -> bool:
-    return line.strip() == "# ///"
+    return line.rstrip("\r\n") == "# ///"
+
+
+def _is_indented_marker(line: str) -> bool:
+    return line[:1] in {" ", "\t"} and line.lstrip(" \t").rstrip("\r\n") in {
+        "# /// script",
+        "# ///",
+    }
 
 
 def _raise_parse_error(message: str, *, path: Path | None = None) -> NoReturn:
@@ -48,12 +55,20 @@ def _find_blocks(source: str, *, path: Path | None = None) -> list[BlockInfo]:
     index = 0
     while index < len(lines):
         line = lines[index]
+        if _is_indented_marker(line):
+            _raise_parse_error(
+                "Metadata markers must start at the first column", path=path
+            )
         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]):
+            if _is_indented_marker(lines[end_index]):
+                _raise_parse_error(
+                    "Metadata markers must start at the first column", path=path
+                )
             end_index += 1
         if end_index >= len(lines):
             _raise_parse_error(
@@ -86,13 +101,12 @@ def _extract_toml_content(
                 path=path,
             )
 
-        trimmed = line.lstrip(" \t")
-        if not trimmed.startswith("#"):
+        if not line.startswith("#"):
             _raise_parse_error(
-                f"Invalid metadata content line {line_number}: expected '#'",
+                f"Invalid metadata content line {line_number}: expected '#' at column 1",
                 path=path,
             )
-        text = trimmed[1:]
+        text = line[1:]
         if text.startswith(" "):
             text = text[1:]
         content_lines.append(text)

{pepscript-0.1.0 → pepscript-0.1.2}/src/pepscript/script.py

@@ -109,6 +109,17 @@ class PEPScript:
         self.meta = parsed.meta if parsed.meta is not None else Metadata()
         self._block = parsed.block
 
+    def _meta_to_write(self) -> Metadata | None:
+        if self.meta.is_empty:
+            return None
+        return self.meta
+
+    def _validated_source_for_write(self) -> str:
+        meta_to_write = self._meta_to_write()
+        if meta_to_write is not None:
+            validate_metadata(meta_to_write, path=self.path)
+        return rewrite_source(self.source, meta=meta_to_write, block=self._block)
+
     def validate(self) -> None:
         """Run structural validation against the current metadata.
 
@@ -145,10 +156,9 @@ class PEPScript:
 
     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=self._meta_to_write(), block=self._block
         )
-        return rewrite_source(self.source, meta=meta_to_write, block=self._block)
 
     def save(self) -> None:
         """Persist the current state to disk, then reload.
@@ -165,7 +175,9 @@ class PEPScript:
         """
         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)
+        write_source(
+            self.path, self._validated_source_for_write(), encoding=self.encoding
+        )
         self.reload()
 
     def save_as(self, path: str | Path) -> None:
@@ -182,7 +194,14 @@ class PEPScript:
             SaveError: If the file cannot be written.
         """
         target = Path(path)
-        write_source(target, self.to_source(), encoding=self.encoding)
+        meta_to_write = self._meta_to_write()
+        if meta_to_write is not None:
+            validate_metadata(meta_to_write, path=target)
+        write_source(
+            target,
+            rewrite_source(self.source, meta=meta_to_write, block=self._block),
+            encoding=self.encoding,
+        )
         self.path = target
         self.reload()
 

{pepscript-0.1.0 → pepscript-0.1.2}/src/pepscript/serialize.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Mapping
+from datetime import date, datetime, time
 import json
 import re
 from typing import Any, cast
@@ -14,6 +15,13 @@ _BARE_KEY_RE = re.compile(r"^[A-Za-z0-9_-]+$")
 _CODING_RE = re.compile(r"^[ \t]*#.*coding[:=][ \t]*[-_.a-zA-Z0-9]+")
 
 
+def _detect_newline(source: str) -> str:
+    match = re.search(r"\r\n|\n|\r", source)
+    if match is None:
+        return "\n"
+    return match.group(0)
+
+
 def _format_key(key: str) -> str:
     if _BARE_KEY_RE.match(key):
         return key
@@ -38,8 +46,20 @@ def _format_value(value: Any) -> str:
         return str(value)
     if isinstance(value, float):
         return repr(value)
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, date):
+        return value.isoformat()
+    if isinstance(value, time):
+        return value.isoformat()
     if value is None:
         raise TypeError("None is not a TOML scalar value")
+    if isinstance(value, Mapping):
+        parts = [
+            f"{_format_key(cast(str, key))} = {_format_value(item)}"
+            for key, item in sorted(value.items())
+        ]
+        return "{ " + ", ".join(parts) + " }"
     if isinstance(value, list):
         inner = ", ".join(_format_value(item) for item in value)
         return f"[{inner}]"
@@ -91,17 +111,17 @@ def serialize_metadata_toml(meta: Metadata) -> str:
     return "\n".join(lines) + "\n"
 
 
-def render_metadata_block(meta: Metadata) -> str:
+def render_metadata_block(meta: Metadata, *, newline: str = "\n") -> str:
     """Render a PEP 723 block from metadata."""
 
     toml = serialize_metadata_toml(meta)
-    output: list[str] = ["# /// script\n"]
+    output: list[str] = [f"# /// script{newline}"]
     for line in toml.splitlines():
         if line:
-            output.append(f"# {line}\n")
+            output.append(f"# {line}{newline}")
         else:
-            output.append("#\n")
-    output.append("# ///\n")
+            output.append(f"#{newline}")
+    output.append(f"# ///{newline}")
     return "".join(output)
 
 
@@ -127,19 +147,21 @@ def rewrite_source(
 ) -> str:
     """Rewrite source with inserted/replaced/removed metadata block."""
 
+    newline = _detect_newline(source)
+
     if block is not None:
         if meta is None:
             return source[: block.start] + source[block.end :]
-        rendered = render_metadata_block(meta)
+        rendered = render_metadata_block(meta, newline=newline)
         return source[: block.start] + rendered + source[block.end :]
 
     if meta is None:
         return source
 
-    rendered = render_metadata_block(meta)
+    rendered = render_metadata_block(meta, newline=newline)
     insert_at = _insertion_offset(source)
     before = source[:insert_at]
     after = source[insert_at:]
 
-    spacer = "\n" if after and not after.startswith("\n") else ""
+    spacer = newline if after and not after.startswith(("\r\n", "\n", "\r")) else ""
     return before + rendered + spacer + after

{pepscript-0.1.0 → pepscript-0.1.2}/src/pepscript/validate.py

@@ -4,8 +4,11 @@ from __future__ import annotations
 
 import re
 from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import date, datetime, time
 from pathlib import Path
 from typing import NoReturn
+from urllib.parse import urlsplit
 
 from .config import ToolConfig
 from .exceptions import MetadataValidationError
@@ -43,10 +46,29 @@ _VALID_MARKER_VARS = frozenset(
     }
 )
 
-_MARKER_KEYWORDS = frozenset({"and", "or", "not", "in"})
+_MARKER_TOKEN_RE = re.compile(
+    r"""
+    \s*(
+        \(
+        |\)
+        |not\s+in\b
+        |and\b
+        |or\b
+        |~=|===|==|!=|<=|>=|<|>
+        |in\b
+        |'(?:[^'\\]|\\.)*'
+        |"(?:[^"\\]|\\.)*"
+        |[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*
+    )
+    """,
+    re.VERBOSE | re.IGNORECASE,
+)
+
 
-# 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")
+@dataclass(slots=True)
+class _MarkerToken:
+    kind: str
+    value: str
 
 
 def _raise_validation_error(message: str, *, path: Path | None = None) -> NoReturn:
@@ -56,7 +78,7 @@ def _raise_validation_error(message: str, *, path: Path | None = None) -> NoRetu
 
 
 def _is_scalar(value: object) -> bool:
-    return isinstance(value, (str, int, float, bool))
+    return isinstance(value, (str, int, float, bool, date, time, datetime))
 
 
 def _validate_tool_value(
@@ -83,16 +105,134 @@ def _validate_tool_value(
 
 
 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
-            )
+    """Validate marker syntax and ensure only known marker variables are used."""
+
+    def tokenize(text: str) -> list[_MarkerToken]:
+        tokens: list[_MarkerToken] = []
+        index = 0
+        length = len(text)
+        while index < length:
+            if text[index].isspace():
+                index += 1
+                continue
+            match = _MARKER_TOKEN_RE.match(text, index)
+            if match is None:
+                _raise_validation_error(
+                    f"{loc} has invalid marker syntax near {text[index:]!r}",
+                    path=path,
+                )
+            value = match.group(1)
+            kind = "IDENT"
+            if value == "(":
+                kind = "LPAREN"
+            elif value == ")":
+                kind = "RPAREN"
+            elif value.lower() == "and":
+                kind = "AND"
+            elif value.lower() == "or":
+                kind = "OR"
+            elif (
+                value.lower() == "in" or re.sub(r"\s+", " ", value.lower()) == "not in"
+            ):
+                kind = "OP"
+            elif value.startswith(("'", '"')):
+                kind = "STRING"
+            elif value in {"~=", "===", "==", "!=", "<=", ">=", "<", ">"}:
+                kind = "OP"
+            tokens.append(_MarkerToken(kind=kind, value=value))
+            index = match.end()
+        return tokens
+
+    class MarkerParser:
+        def __init__(self, tokens: list[_MarkerToken]):
+            self.tokens = tokens
+            self.index = 0
+
+        def current(self) -> _MarkerToken | None:
+            if self.index >= len(self.tokens):
+                return None
+            return self.tokens[self.index]
+
+        def consume(self, kind: str) -> _MarkerToken:
+            token = self.current()
+            if token is None or token.kind != kind:
+                _raise_validation_error(
+                    f"{loc} has invalid marker syntax",
+                    path=path,
+                )
+            self.index += 1
+            return token
+
+        def parse(self) -> None:
+            self.parse_or_expression()
+            if self.current() is not None:
+                _raise_validation_error(
+                    f"{loc} has invalid marker syntax",
+                    path=path,
+                )
+
+        def parse_or_expression(self) -> None:
+            self.parse_and_expression()
+            while (token := self.current()) is not None and token.kind == "OR":
+                self.consume("OR")
+                self.parse_and_expression()
+
+        def parse_and_expression(self) -> None:
+            self.parse_term()
+            while (token := self.current()) is not None and token.kind == "AND":
+                self.consume("AND")
+                self.parse_term()
+
+        def parse_term(self) -> None:
+            token = self.current()
+            if token is None:
+                _raise_validation_error(
+                    f"{loc} has invalid marker syntax",
+                    path=path,
+                )
+            if token.kind == "LPAREN":
+                self.consume("LPAREN")
+                self.parse_or_expression()
+                self.consume("RPAREN")
+                return
+            self.parse_comparison()
+
+        def parse_comparison(self) -> None:
+            self.parse_operand()
+            self.consume("OP")
+            self.parse_operand()
+
+        def parse_operand(self) -> None:
+            token = self.current()
+            if token is None or token.kind not in {"IDENT", "STRING"}:
+                _raise_validation_error(
+                    f"{loc} has invalid marker syntax",
+                    path=path,
+                )
+            if token.kind == "IDENT" and token.value not in _VALID_MARKER_VARS:
+                _raise_validation_error(
+                    f"{loc} has unknown marker variable {token.value!r}",
+                    path=path,
+                )
+            self.index += 1
+
+    MarkerParser(tokenize(marker)).parse()
+
+
+def _validate_direct_reference(url: str, *, loc: str, path: Path | None = None) -> None:
+    if not url:
+        _raise_validation_error(f"{loc} has an empty direct reference URL", path=path)
+    if any(character.isspace() for character in url):
+        _raise_validation_error(
+            f"{loc} has invalid whitespace in direct reference URL {url!r}",
+            path=path,
+        )
+    parsed = urlsplit(url)
+    if not parsed.scheme or not (parsed.netloc or parsed.path):
+        _raise_validation_error(
+            f"{loc} has an invalid direct reference URL {url!r}",
+            path=path,
+        )
 
 
 def _validate_pep508_dependency(
@@ -115,8 +255,12 @@ def _validate_pep508_dependency(
     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
+    if is_url:
+        name_scope, url_part = req_part.split("@", 1)
+        name_scope = name_scope.strip()
+        _validate_direct_reference(url_part.strip(), loc=loc, path=path)
+    else:
+        name_scope = 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)
@@ -141,7 +285,9 @@ def _validate_pep508_dependency(
         for extra in rest[1:close].split(","):
             e = extra.strip()
             if not e:
-                continue
+                _raise_validation_error(
+                    f"{loc} has an empty extra in {dep!r}", path=path
+                )
             if not _NAME_RE.match(e):
                 _raise_validation_error(f"{loc} has invalid extra {e!r}", path=path)
         rest = rest[close + 1 :].strip()
@@ -154,6 +300,13 @@ def _validate_pep508_dependency(
 
     # Version specifiers (not applicable for URL requirements)
     if not is_url and rest:
+        if rest.startswith("("):
+            if not rest.endswith(")"):
+                _raise_validation_error(
+                    f"{loc} has unclosed version specifier parentheses in {dep!r}",
+                    path=path,
+                )
+            rest = rest[1:-1].strip()
         for clause in rest.split(","):
             if not _VERSION_CLAUSE_RE.match(clause):
                 _raise_validation_error(