pycodify 0.1.3__tar.gz → 0.2.1__tar.gz

pycodify-0.2.1/.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

{pycodify-0.1.3 → pycodify-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pycodify
-Version: 0.1.3
+Version: 0.2.1
 Summary: Python source code as a serialization format with automatic import resolution
 Project-URL: Homepage, https://github.com/OpenHCSDev/pycodify
 Project-URL: Documentation, https://pycodify.readthedocs.io

pycodify-0.2.1/docs/api.rst

@@ -0,0 +1,41 @@
+API orientation
+===============
+
+``Assignment`` and ``CodeBlock``
+   Structured top-level source items.
+
+``generate_python_source(obj, header="", clean_mode=False)``
+   Generate complete executable source and required imports, with shared and
+   repeated absolute paths bound once at the top.
+
+``to_source(value, context=None)``
+   Format one value into a ``SourceFragment``.
+
+``SourceFormatter``
+   Nominal extension point. Subclasses implement ``can_format`` and ``format``;
+   application-specific formatters register without changing pycodify core.
+
+``resolve_imports``
+   Resolve import requirements and aliases for colliding names.
+
+``FormatContext`` and ``SourceFragment``
+   Immutable formatting state and output records.
+
+``imported_name(module, qualname, context)``
+   Spell an importable object by its qualified name, honouring collision aliases.
+
+``PythonSourceLiteral``
+   Base for values that spell their own source through ``source_fragment``.
+
+``PathRendering``, ``PathCollector``, ``PathFactoring``, ``PathConstructor``
+   How a render pass spells paths: plainly, while recording, or through the
+   document's path bindings.
+
+The canonical import surface is ``pycodify.__all__``.
+
+Public API
+----------
+
+.. automodule:: pycodify
+   :members:
+   :member-order: bysource

{pycodify-0.1.3 → pycodify-0.2.1}/docs/architecture.rst

@@ -6,7 +6,8 @@ Two-Pass Algorithm
 
 Generating executable source requires knowing import aliases before emitting code. But aliases depend on detecting collisions, which requires visiting all types first. This creates a dependency: code generation requires alias resolution, but alias resolution requires traversing the object graph.
 
-pycodify solves this with two passes:
+pycodify solves this with two passes, preceded by a path-discovery pass
+(see *Path factoring* below):
 
 1. **Collection pass**: Traverse the object, emit code fragments, and collect
    ``(module, name)`` import pairs.
@@ -31,12 +32,26 @@ Each type maps to a ``SourceFormatter`` that emits a ``SourceFragment(code, impo
            return isinstance(value, Enum)
 
        def format(self, value: Enum, context: FormatContext) -> SourceFragment:
-           cls = value.__class__
-           import_pair = (cls.__module__, cls.__name__)
-           name = context.name_mappings.get(import_pair, cls.__name__)
-           return SourceFragment(f"{name}.{value.name}", frozenset([import_pair]))
+           enum_type = imported_name(type(value).__module__, type(value).__qualname__, context)
+           return SourceFragment(f"{enum_type.code}.{value.name}", enum_type.imports)
 
-Priority-based dispatch selects the most specific formatter. Domain extensions add formatters without modifying core code.
+Priority-based dispatch selects the most specific formatter. Domain extensions add formatters without modifying core code. A value no formatter accepts raises ``TypeError``: pycodify never emits ``repr`` text it cannot load back.
+
+Qualified names
+---------------
+
+``imported_name(module, qualname, context)`` is the one rule for spelling an
+importable object. It imports the root of ``__qualname__`` and spells the rest as
+attribute access, so ``Outer.Mode.FAST`` imports ``Outer``. Enum members,
+classes, functions, class-bound methods, named tuples and dataclass constructors
+all use it. Objects defined inside a function raise ``TypeError``.
+
+Values that own their spelling
+------------------------------
+
+A value whose source is not its constructor subclasses ``PythonSourceLiteral``
+and implements ``source_fragment(context)``, typically building on
+``imported_name`` so collision aliases apply.
 
 Core Components
 ---------------
@@ -49,7 +64,7 @@ Core Components
 
 **FormatContext**
   Carries indentation depth, ``clean_mode``, the ``(module, name)`` to
-  local-name mapping, and caller-owned typed extensions. ``indented()`` returns
+  local-name mapping, and the pass's ``PathRendering``. ``indented()`` returns
   a copied context and does not mutate its caller.
 
 **resolve_imports**
@@ -60,27 +75,17 @@ Core Components
   Orchestrates collection, resolution, and regeneration to produce a complete
   source string.
 
-Immutable typed context extensions
-----------------------------------
-
-``FormatContext`` is frozen. Its default mappings are read-only mapping proxies,
-and context evolution uses dataclass replacement rather than mutation. A host
-may supply an ``extensions`` mapping keyed by the exact nominal type of each
-rendering policy or state record. A formatter retrieves one value with
-``context.extension(ExtensionType)``; pycodify does not search base classes,
-string keys, or a fallback chain.
-
-``generate_python_source(..., context=context)`` threads the caller's context
-through collection and regeneration. Import resolution replaces only
-``name_mappings`` for the second pass, so typed extensions and all other context
-fields survive. When a context is supplied, its ``clean_mode`` is authoritative;
-the separate ``clean_mode=`` argument is used only when pycodify constructs the
-context.
+Path factoring
+--------------
 
-Extensions provide formatting context, not formatter dispatch. New value
-families still extend the ``SourceFormatter`` registry, while the exact extension
-type allows that formatter to obtain host-owned rendering information without
-adding host imports or fields to pycodify core.
+``generate_python_source`` first renders the document with a ``PathCollector``
+on ``FormatContext.paths`` to record every ``pathlib.Path`` value. A
+``PathFactoring`` plan then binds each directory shared by two or more absolute
+paths (``path_root = Path('/data/screen')``) and each repeated absolute path
+(``path_1 = path_root / 'plate_A'``) once, at the top of the document, and the
+two rendering passes spell those paths through the bindings. Relative paths and
+strings are never factored. ``to_source`` alone uses the base ``PathRendering``,
+which spells each path as ``Path('...')``.
 
 Clean Mode
 ----------
@@ -107,25 +112,13 @@ not sandboxing or validation of generated programs. Hosts must restrict inputs
 and custom formatters to trusted sources, review persisted code before running
 it, and define their own compatibility policy for imported domain APIs.
 
-Lazy Dataclass Integration
----------------------------
-
-For dataclasses with ``__getattribute__`` interception (used for hierarchical config inheritance), formatters use ``object.__getattribute__`` to access raw field values without triggering lazy resolution:
-
-.. code-block:: python
-
-   # In DataclassFormatter
-   if hasattr(instance, "_resolve_field_value"):
-       # Bypass __getattribute__ to get raw None vs concrete value
-       current_value = object.__getattribute__(instance, field_name)
-   else:
-       current_value = getattr(instance, field_name)
-
-This distinguishes explicitly-set values from inherited ones during serialization.
-
 Module Structure
 ----------------
 
 - **core.py**: Main API (``Assignment``, ``generate_python_source``)
-- **formatters.py**: Built-in formatters (dataclass, enum, primitive types)
+- **formatters.py**: Built-in formatters (dataclass, enum, class, callable, primitive types)
+- **paths.py**: Document-level path factoring
+
+Lazy configuration dataclasses (ObjectState) are formatted by
+``objectstate.codegen``, which registers its own formatter.
 - **imports.py**: Import resolution and collision handling

{pycodify-0.1.3 → pycodify-0.2.1}/docs/conf.py

@@ -1,6 +1,7 @@
 """Sphinx configuration for pycodify."""
-import os
+
 import sys
+from importlib import import_module
 from pathlib import Path
 
 # Add source to path
@@ -10,8 +11,8 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
 project = "pycodify"
 copyright = "2024, Tristan Simas"
 author = "Tristan Simas"
-version = "0.1"
-release = "0.1.3"
+release = import_module("pycodify").__version__
+version = ".".join(release.split(".")[:2])
 
 # General configuration
 extensions = [

{pycodify-0.1.3 → pycodify-0.2.1}/docs/usage.rst

@@ -117,62 +117,37 @@ level. ``name_mappings`` maps ``(module, imported_name)`` pairs to the local
 names chosen by ``resolve_imports``; callers normally let
 ``generate_python_source`` populate it during the second pass.
 
-Typed rendering extensions
---------------------------
+Values that own their source
+----------------------------
 
-A host can attach immutable rendering context without adding host-specific state
-to pycodify. Keys are exact nominal types, and the same context reaches both
-render passes:
+A value whose source is not its dataclass constructor implements
+``PythonSourceLiteral``:
 
 .. code-block:: python
 
    from dataclasses import dataclass
-   from types import MappingProxyType
 
    from pycodify import (
        Assignment,
        FormatContext,
-       SourceFormatter,
+       PythonSourceLiteral,
        SourceFragment,
        generate_python_source,
+       imported_name,
    )
 
    @dataclass(frozen=True)
-   class RenderPolicy:
-       marker: str
-
-   class PolicyValue:
-       pass
-
-   class PolicyValueFormatter(SourceFormatter):
-       priority = 200
-
-       def can_format(self, value):
-           return isinstance(value, PolicyValue)
-
-       def format(self, value, context):
-           del value
-           policy = context.extension(RenderPolicy)
-           if policy is None:
-               raise RuntimeError("RenderPolicy is required")
-           return SourceFragment(repr(policy.marker))
-
-   context = FormatContext(
-       clean_mode=True,
-       extensions=MappingProxyType(
-           {RenderPolicy: RenderPolicy(marker="preserved")}
-       ),
-   )
-   source = generate_python_source(
-       Assignment("value", PolicyValue()),
-       context=context,
-   )
-   assert source == "value = 'preserved'"
+   class RegistryLookup(PythonSourceLiteral):
+       key: str
+
+       def source_fragment(self, context: FormatContext) -> SourceFragment:
+           lookup = imported_name("myapp.registry", "get_function", context)
+           return SourceFragment(f"{lookup.code}({self.key!r})", lookup.imports)
 
-``extension(RenderPolicy)`` does not return a value stored under a base class or
-string key. This exact-type lookup keeps extension ownership explicit. Treat the
-extension mapping as immutable; use a new ``FormatContext`` when the host needs
-different state.
+   source = generate_python_source(Assignment("func", RegistryLookup("gauss")))
+   # from myapp.registry import get_function
+   #
+   # func = get_function('gauss')
 
 Nested Dataclasses
 -------------------

{pycodify-0.1.3 → pycodify-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycodify"
-version = "0.1.3"
+version = "0.2.1"
 description = "Python source code as a serialization format with automatic import resolution"
 authors = [{name = "Tristan Simas", email = "tristan.simas@mail.mcgill.ca"}]
 license = {text = "MIT"}

{pycodify-0.1.3 → pycodify-0.2.1}/src/pycodify/__init__.py

@@ -1,20 +1,24 @@
+# Register default formatters
+from . import formatters as _formatters  # noqa: F401
 from .core import (
     Assignment,
     BlankLine,
     CodeBlock,
     Comment,
     FormatContext,
+    PathRendering,
+    PythonSourceLiteral,
     SourceFormatter,
     SourceFragment,
     generate_python_source,
+    imported_name,
     to_source,
 )
+from .documents import SourceDocument
 from .imports import resolve_imports
+from .paths import PathCollector, PathConstructor, PathFactoring
 
-# Register default formatters
-from . import formatters as _formatters  # noqa: F401
-
-__version__ = "0.1.3"
+__version__ = "0.2.1"
 
 __all__ = [
     "Assignment",
@@ -22,9 +26,16 @@ __all__ = [
     "CodeBlock",
     "Comment",
     "FormatContext",
+    "PathCollector",
+    "PathConstructor",
+    "PathFactoring",
+    "PathRendering",
+    "PythonSourceLiteral",
+    "SourceDocument",
     "SourceFormatter",
     "SourceFragment",
     "generate_python_source",
+    "imported_name",
     "resolve_imports",
     "to_source",
 ]

{pycodify-0.1.3 → pycodify-0.2.1}/src/pycodify/core.py

@@ -1,10 +1,11 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
+from collections.abc import Iterable, Mapping
 from dataclasses import dataclass, field, replace
-from collections.abc import Mapping
+from pathlib import Path
 from types import MappingProxyType
-from typing import Any, ClassVar, FrozenSet, Iterable, List, Tuple
+from typing import Any, ClassVar
 
 
 @dataclass(frozen=True)
@@ -12,39 +13,78 @@ class SourceFragment:
     """Result of serializing a value to Python source."""
 
     code: str
-    imports: FrozenSet[Tuple[str, str]] = frozenset()
+    imports: frozenset[tuple[str, str]] = frozenset()
 
-    def __add__(self, other: "SourceFragment") -> "SourceFragment":
+    def __add__(self, other: SourceFragment) -> SourceFragment:
         return SourceFragment(
             code=self.code + other.code,
             imports=self.imports | other.imports,
         )
 
 
+class PathRendering:
+    """How one render pass spells :class:`pathlib.Path` values.
+
+    The base spells every path as its own constructor call. Subclasses in
+    :mod:`pycodify.paths` record or substitute paths for document-level
+    factoring.
+    """
+
+    def path_source(self, value: Path, context: FormatContext) -> SourceFragment:
+        constructor = imported_name("pathlib", "Path", context)
+        return SourceFragment(
+            f"{constructor.code}({str(value)!r})",
+            constructor.imports,
+        )
+
+
 @dataclass(frozen=True)
 class FormatContext:
     """Context passed through serialization."""
 
     indent: int = 0
     clean_mode: bool = False
-    name_mappings: Mapping[Tuple[str, str], str] = field(
-        default_factory=lambda: MappingProxyType({})
-    )
-    extensions: Mapping[type[object], object] = field(
+    name_mappings: Mapping[tuple[str, str], str] = field(
         default_factory=lambda: MappingProxyType({})
     )
+    paths: PathRendering = field(default_factory=PathRendering)
 
-    def indented(self) -> "FormatContext":
+    def indented(self) -> FormatContext:
         return replace(self, indent=self.indent + 1)
 
     @property
     def indent_str(self) -> str:
         return "    " * self.indent
 
-    def extension(self, extension_type: type[Any]) -> Any | None:
-        """Return one caller-owned rendering extension by exact nominal type."""
 
-        return self.extensions.get(extension_type)
+def imported_name(module: str, qualname: str, context: FormatContext) -> SourceFragment:
+    """Spell an importable object by its module and ``__qualname__``.
+
+    The root of the qualified name is imported (under its collision alias, if
+    any) and the rest is spelled as attribute access, so nested classes, enums
+    and functions load back as themselves. Objects defined inside a function
+    have no import path and are rejected.
+    """
+
+    if "<locals>" in qualname:
+        raise TypeError(
+            f"{module}.{qualname} is defined inside a function and cannot be "
+            "imported by generated source."
+        )
+    root, dot, nested = qualname.partition(".")
+    if module == "builtins":
+        return SourceFragment(qualname)
+    import_pair = (module, root)
+    name = context.name_mappings.get(import_pair, root)
+    return SourceFragment(f"{name}{dot}{nested}", frozenset({import_pair}))
+
+
+class PythonSourceLiteral(ABC):
+    """A value that spells its own Python source expression."""
+
+    @abstractmethod
+    def source_fragment(self, context: FormatContext) -> SourceFragment:
+        """Return the expression that reconstructs this value, with its imports."""
 
 
 @dataclass(frozen=True)
@@ -65,10 +105,10 @@ class Assignment:
 
 @dataclass(frozen=True)
 class CodeBlock:
-    items: Tuple[Any, ...]
+    items: tuple[Any, ...]
 
     @classmethod
-    def from_items(cls, items: Iterable[Any]) -> "CodeBlock":
+    def from_items(cls, items: Iterable[Any]) -> CodeBlock:
         return cls(tuple(items))
 
 
@@ -77,11 +117,11 @@ class SourceFormatter(ABC):
 
     priority: int = 0
 
-    _registry: ClassVar[List["SourceFormatter"]] = []
-    _sorted_registry: ClassVar[List["SourceFormatter"]] = []
+    _registry: ClassVar[list[SourceFormatter]] = []
+    _sorted_registry: ClassVar[list[SourceFormatter]] = []
     _registry_dirty: ClassVar[bool] = False
 
-    def __init_subclass__(cls, **kwargs):
+    def __init_subclass__(cls, **kwargs: Any) -> None:
         super().__init_subclass__(**kwargs)
         if getattr(cls, "__abstract__", False):
             return
@@ -99,12 +139,12 @@ class SourceFormatter(ABC):
         raise NotImplementedError
 
     @classmethod
-    def register(cls, formatter: "SourceFormatter") -> None:
+    def register(cls, formatter: SourceFormatter) -> None:
         cls._registry.append(formatter)
         cls._registry_dirty = True
 
     @classmethod
-    def _iter_registry(cls) -> List["SourceFormatter"]:
+    def _iter_registry(cls) -> list[SourceFormatter]:
         if cls._registry_dirty:
             cls._sorted_registry = sorted(
                 cls._registry,
@@ -115,7 +155,7 @@ class SourceFormatter(ABC):
         return cls._sorted_registry
 
     @classmethod
-    def get_formatter(cls, value: Any) -> "SourceFormatter":
+    def get_formatter(cls, value: Any) -> SourceFormatter:
         for formatter in cls._iter_registry():
             if formatter.can_format(value):
                 return formatter
@@ -135,21 +175,28 @@ def generate_python_source(
     obj: Any,
     header: str = "",
     clean_mode: bool = False,
-    *,
-    context: FormatContext | None = None,
 ) -> str:
-    """Generate complete Python source with imports."""
+    """Generate complete Python source with imports.
+
+    Absolute paths that share a root or repeat are bound once at the top of the
+    document (see :mod:`pycodify.paths`).
+    """
     from .imports import resolve_imports
+    from .paths import PathCollector, PathFactoring
 
-    ctx = context or FormatContext(clean_mode=clean_mode)
-    fragment = to_source(obj, ctx)
+    ctx = FormatContext(clean_mode=clean_mode)
+    collector = PathCollector()
+    to_source(obj, replace(ctx, paths=collector))
+    factoring = PathFactoring.from_occurrences(collector.values)
+    body = factoring.document(obj)
+    ctx = replace(ctx, paths=factoring)
 
+    fragment = to_source(body, ctx)
     import_lines, name_mappings = resolve_imports(fragment.imports)
-
     ctx = replace(ctx, name_mappings=MappingProxyType(name_mappings))
-    fragment = to_source(obj, ctx)
+    fragment = to_source(body, ctx)
 
-    code_lines: List[str] = []
+    code_lines: list[str] = []
     if header:
         code_lines.extend(header.splitlines())
         code_lines.append("")

pycodify-0.2.1/src/pycodify/documents.py

@@ -0,0 +1,65 @@
+"""A dataclass saved as one Python module of assignments."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import MISSING, Field, fields
+from typing import Any, TypeVar
+
+from .core import Assignment, BlankLine, CodeBlock, generate_python_source
+
+DocumentT = TypeVar("DocumentT", bound="SourceDocument")
+
+
+class SourceDocument:
+    """A dataclass whose constructor fields are a module's public assignments.
+
+    Each ``init=True`` field is written as one module-level assignment named
+    after the field, in declaration order, and read back by that name. The
+    field declaration is the only place the name is spelled. A field with a
+    default may be absent from a loaded module; a field without one must be
+    assigned. ``init=False`` fields are not part of the saved module.
+    """
+
+    __slots__ = ()
+
+    @classmethod
+    def assignment_fields(cls) -> tuple[Field[Any], ...]:
+        """Return the fields saved as assignments, in declaration order."""
+        return tuple(field for field in fields(cls) if field.init)  # type: ignore[arg-type]
+
+    @classmethod
+    def assignment_names(cls) -> tuple[str, ...]:
+        """Return the names this document assigns at module level."""
+        return tuple(field.name for field in cls.assignment_fields())
+
+    @classmethod
+    def from_namespace(cls: type[DocumentT], namespace: Mapping[str, object]) -> DocumentT:
+        """Build the document from the names an executed module defines."""
+        values: dict[str, object] = {}
+        for field in cls.assignment_fields():
+            if field.name in namespace:
+                values[field.name] = namespace[field.name]
+            elif field.default is MISSING and field.default_factory is MISSING:
+                raise ValueError(f"{cls.__name__} source must define {field.name!r}.")
+        return cls(**values)
+
+    @classmethod
+    def from_source(cls: type[DocumentT], source: str) -> DocumentT:
+        """Execute Python source and build the document from its assignments."""
+        namespace: dict[str, object] = {}
+        exec(compile(source, f"<{cls.__name__}>", "exec"), namespace)  # noqa: S102
+        return cls.from_namespace(namespace)
+
+    def body(self) -> CodeBlock:
+        """Return one assignment per saved field, separated by blank lines."""
+        items: list[object] = []
+        for name in self.assignment_names():
+            if items:
+                items.append(BlankLine())
+            items.append(Assignment(name, getattr(self, name)))
+        return CodeBlock.from_items(items)
+
+    def to_source(self, *, header: str = "", clean_mode: bool = False) -> str:
+        """Render the document as a complete Python module."""
+        return generate_python_source(self.body(), header=header, clean_mode=clean_mode)