pycodify 0.1.2__tar.gz → 0.2.0__tar.gz

pycodify-0.2.0/.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.2 → pycodify-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pycodify
-Version: 0.1.2
+Version: 0.2.0
 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
@@ -49,7 +49,7 @@ class Config:
     value: int = 42
 
 config = Config(name="production", value=100)
-code = generate_python_source(Assignment("config", config), clean_mode=True)
+code = generate_python_source(Assignment("config", config))
 print(code)
 # Output:
 # from __main__ import Config
@@ -62,9 +62,12 @@ print(code)
 |--------|:--------:|:-----------:|:--------:|:---------------:|:-------------:|
 | pickle | ✗ | ✗ | ✗ | ✓ | ✗ |
 | JSON/YAML | ✓ | ✓ | ✓ | ✗ | ✓ |
-| Python source | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Python source | ✓ | ✓ | ✓ | ✓ | Depends on imported APIs |
 
-Binary formats like `pickle` cannot be diffed, inspected, or edited. Text formats like JSON lose type information. Python source code has all desired properties: it is diffable, inspectable, editable, type-preserving, and cross-version stable.
+Binary formats like `pickle` cannot be diffed, inspected, or edited. Text
+formats like JSON lose type information. Python source is diffable, inspectable,
+editable, and type-preserving, but replay still depends on the imported APIs and
+constructor signatures remaining compatible.
 
 ## Features
 
@@ -76,6 +79,14 @@ Binary formats like `pickle` cannot be diffed, inspected, or edited. Text format
 
 ## Documentation
 
+Explicit mode is the default (``clean_mode=False``), preserving every field for
+reproducibility. Pass ``clean_mode=True`` only when concise, default-eliding
+source is desired.
+
+Generated output is executable Python, not a sandboxed data format. Review it
+before execution and never call `exec` on source generated from untrusted
+objects, custom formatters, headers, or edited files.
+
 Full documentation available at [pycodify.readthedocs.io](https://pycodify.readthedocs.io)
 
 ## Installation

{pycodify-0.1.2 → pycodify-0.2.0}/README.md

@@ -14,7 +14,7 @@ class Config:
     value: int = 42
 
 config = Config(name="production", value=100)
-code = generate_python_source(Assignment("config", config), clean_mode=True)
+code = generate_python_source(Assignment("config", config))
 print(code)
 # Output:
 # from __main__ import Config
@@ -27,9 +27,12 @@ print(code)
 |--------|:--------:|:-----------:|:--------:|:---------------:|:-------------:|
 | pickle | ✗ | ✗ | ✗ | ✓ | ✗ |
 | JSON/YAML | ✓ | ✓ | ✓ | ✗ | ✓ |
-| Python source | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Python source | ✓ | ✓ | ✓ | ✓ | Depends on imported APIs |
 
-Binary formats like `pickle` cannot be diffed, inspected, or edited. Text formats like JSON lose type information. Python source code has all desired properties: it is diffable, inspectable, editable, type-preserving, and cross-version stable.
+Binary formats like `pickle` cannot be diffed, inspected, or edited. Text
+formats like JSON lose type information. Python source is diffable, inspectable,
+editable, and type-preserving, but replay still depends on the imported APIs and
+constructor signatures remaining compatible.
 
 ## Features
 
@@ -41,6 +44,14 @@ Binary formats like `pickle` cannot be diffed, inspected, or edited. Text format
 
 ## Documentation
 
+Explicit mode is the default (``clean_mode=False``), preserving every field for
+reproducibility. Pass ``clean_mode=True`` only when concise, default-eliding
+source is desired.
+
+Generated output is executable Python, not a sandboxed data format. Review it
+before execution and never call `exec` on source generated from untrusted
+objects, custom formatters, headers, or edited files.
+
 Full documentation available at [pycodify.readthedocs.io](https://pycodify.readthedocs.io)
 
 ## Installation

pycodify-0.2.0/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.2.0/docs/architecture.rst

@@ -0,0 +1,124 @@
+Architecture
+============
+
+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, 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.
+2. **Resolution**: ``resolve_imports`` sorts the pairs, detects names exported by
+   more than one module, and derives aliases from each module path.
+3. **Regeneration pass**: Re-traverse with the resolved ``name_mappings`` and
+   emit final code using those local names.
+
+This is not an optimization—it is structurally necessary. A single-pass algorithm cannot know whether ``Config`` needs aliasing until it has seen all types that might also be named ``Config``.
+
+Extensible Formatter Registry
+------------------------------
+
+Each type maps to a ``SourceFormatter`` that emits a ``SourceFragment(code, imports)``. Formatters register via ``__init_subclass__``—defining a formatter class automatically adds it to the registry:
+
+.. code-block:: python
+
+   class EnumFormatter(SourceFormatter):
+       priority = 70
+
+       def can_format(self, value: Any) -> bool:
+           return isinstance(value, Enum)
+
+       def format(self, value: Enum, context: FormatContext) -> SourceFragment:
+           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. 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
+---------------
+
+**SourceFormatter**
+  Base class for all formatters. Subclasses implement ``can_format()`` and ``format()`` methods.
+
+**SourceFragment**
+  Represents a piece of generated code with its required imports.
+
+**FormatContext**
+  Carries indentation depth, ``clean_mode``, the ``(module, name)`` to
+  local-name mapping, and the pass's ``PathRendering``. ``indented()`` returns
+  a copied context and does not mutate its caller.
+
+**resolve_imports**
+  Detects collisions and returns import lines plus the name mapping used by the
+  regeneration pass.
+
+**generate_python_source**
+  Orchestrates collection, resolution, and regeneration to produce a complete
+  source string.
+
+Path factoring
+--------------
+
+``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
+----------
+
+Clean mode omits fields matching their default values. This requires:
+
+1. Accessing the dataclass field defaults
+2. Comparing current values to defaults
+3. Omitting fields where ``current_value == default_value``
+
+Explicit mode includes all fields for complete reproducibility.
+
+Stability and trust boundary
+----------------------------
+
+Import ordering and collision aliases are deterministic for a fixed set of
+``(module, name)`` pairs. The library does not promise that arbitrary object
+graphs produce byte-identical text across runs: container iteration, object
+``repr`` implementations, custom formatters, and dependency versions can all
+affect output or replay.
+
+The output is executable Python. pycodify owns formatting and import resolution,
+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.
+
+Module Structure
+----------------
+
+- **core.py**: Main API (``Assignment``, ``generate_python_source``)
+- **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.2 → pycodify-0.2.0}/docs/conf.py

@@ -1,16 +1,18 @@
 """Sphinx configuration for pycodify."""
-import os
+
 import sys
+from importlib import import_module
+from pathlib import Path
 
 # Add source to path
-sys.path.insert(0, os.path.abspath("../src"))
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
 
 # Project information
 project = "pycodify"
 copyright = "2024, Tristan Simas"
 author = "Tristan Simas"
-version = "0.1.0"
-release = "0.1.0"
+release = import_module("pycodify").__version__
+version = ".".join(release.split(".")[:2])
 
 # General configuration
 extensions = [
@@ -54,7 +56,6 @@ autosummary_generate = True
 html_theme = "sphinx_rtd_theme"
 html_theme_options = {
     "logo_only": False,
-    "display_version": True,
     "prev_next_buttons_location": "bottom",
     "style_external_links": False,
     "vcs_pageview_mode": "",
@@ -70,4 +71,3 @@ html_favicon = None
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
 }
-

pycodify-0.2.0/docs/index.rst

@@ -0,0 +1,38 @@
+pycodify
+========
+
+pycodify serializes Python objects to executable Python source while resolving
+imports and name collisions.
+
+Quick start
+-----------
+
+.. code-block:: python
+
+   from dataclasses import dataclass
+   from pycodify import Assignment, generate_python_source
+
+   @dataclass
+   class Config:
+       name: str = "default"
+       value: int = 42
+
+   config = Config(name="production", value=100)
+   code = generate_python_source(Assignment("config", config))
+
+Explicit mode is the default (``clean_mode=False``) and includes default-valued
+fields. Pass ``clean_mode=True`` only when default elision is desired.
+
+.. toctree::
+   :maxdepth: 2
+
+   usage
+   api
+   architecture
+
+Ownership
+---------
+
+pycodify owns source fragments, imports, formatter registration, collision
+handling, and generic Python formatting. Host packages own their domain
+formatters and round-trip policies.

pycodify-0.2.0/docs/usage.rst

@@ -0,0 +1,201 @@
+Usage Guide
+===========
+
+Basic Usage
+-----------
+
+The simplest way to use pycodify is to generate source code for an object:
+
+.. code-block:: python
+
+   from pycodify import Assignment, generate_python_source
+   from dataclasses import dataclass
+
+   @dataclass
+   class ProcessingConfig:
+       input_path: str = "/data/input"
+       output_path: str = "/data/output"
+       num_workers: int = 4
+
+   config = ProcessingConfig(
+       input_path="/data/production",
+       num_workers=8
+   )
+
+   code = generate_python_source(
+       Assignment("config", config),
+       clean_mode=True
+   )
+   print(code)
+
+Clean Mode vs Explicit Mode
+----------------------------
+
+**Clean mode** omits fields that match their default values and must be enabled
+explicitly:
+
+.. code-block:: python
+
+   # Clean mode - concise
+   code = generate_python_source(assignment, clean_mode=True)
+   # Output: config = ProcessingConfig(input_path='/data/production', num_workers=8)
+
+**Explicit mode** includes all fields for complete reproducibility and is the
+default:
+
+.. code-block:: python
+
+   # Explicit mode - complete
+   code = generate_python_source(assignment, clean_mode=False)
+   # Output: config = ProcessingConfig(
+   #     input_path='/data/production',
+   #     output_path='/data/output',
+   #     num_workers=8
+   # )
+
+Working with Enums
+------------------
+
+Enums are serialized with their full qualified names:
+
+.. code-block:: python
+
+   from enum import Enum
+
+   class ImageFormat(Enum):
+       JPEG = "jpeg"
+       PNG = "png"
+       TIFF = "tiff"
+
+   @dataclass
+   class ImageConfig:
+       format: ImageFormat = ImageFormat.JPEG
+
+   config = ImageConfig(format=ImageFormat.PNG)
+   code = generate_python_source(Assignment("config", config))
+   # Output includes: from __main__ import ImageFormat
+   # config = ImageConfig(format=ImageFormat.PNG)
+
+Handling Import Collisions
+---------------------------
+
+When multiple modules export the same name, pycodify aliases every colliding
+import. Aliases are derived from the complete module path, with dots replaced
+by underscores:
+
+.. code-block:: python
+
+   # pycodify generates:
+   # from package.module_a import Config as Config_package_module_a
+   # from package.module_b import Config as Config_package_module_b
+   # left = Config_package_module_a(...)
+   # right = Config_package_module_b(...)
+
+``resolve_imports`` sorts modules and imported names before emitting them, so a
+given set of import requirements has stable ordering and aliases. Whole-file
+byte-for-byte stability additionally depends on value iteration order, ``repr``
+implementations, and any custom formatters.
+
+Formatting one value
+--------------------
+
+``to_source`` returns a ``SourceFragment`` rather than a complete file. Pass a
+``FormatContext`` when indentation, clean mode, or already-resolved names must
+be controlled explicitly:
+
+.. code-block:: python
+
+   from pycodify import FormatContext, to_source
+
+   context = FormatContext(indent=1, clean_mode=True)
+   fragment = to_source([1, 2], context)
+   print(fragment.code)
+   print(fragment.imports)
+
+``FormatContext.indented()`` returns a copy with one additional indentation
+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.
+
+Values that own their source
+----------------------------
+
+A value whose source is not its dataclass constructor implements
+``PythonSourceLiteral``:
+
+.. code-block:: python
+
+   from dataclasses import dataclass
+
+   from pycodify import (
+       Assignment,
+       FormatContext,
+       PythonSourceLiteral,
+       SourceFragment,
+       generate_python_source,
+       imported_name,
+   )
+
+   @dataclass(frozen=True)
+   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)
+
+   source = generate_python_source(Assignment("func", RegistryLookup("gauss")))
+   # from myapp.registry import get_function
+   #
+   # func = get_function('gauss')
+
+Nested Dataclasses
+-------------------
+
+Nested dataclasses are properly serialized with all necessary imports:
+
+.. code-block:: python
+
+   from dataclasses import dataclass, field
+
+   @dataclass
+   class DatabaseConfig:
+       host: str = "localhost"
+       port: int = 5432
+
+   @dataclass
+   class AppConfig:
+       database: DatabaseConfig = field(default_factory=DatabaseConfig)
+       debug: bool = False
+
+   config = AppConfig(
+       database=DatabaseConfig(host="prod.db.internal"),
+       debug=True
+   )
+
+   code = generate_python_source(Assignment("config", config))
+   # Generates imports for both DatabaseConfig and AppConfig
+
+Executing Generated Code
+------------------------
+
+The generated code is executable Python:
+
+.. code-block:: python
+
+   code = generate_python_source(assignment)
+   namespace = {}
+   exec(code, namespace)
+   recreated_config = namespace["config"]
+   assert recreated_config == original_config
+
+.. warning::
+
+   Generated output is executable Python, not a sandboxed data format. Execute
+   it only when the input objects, custom formatters, header, and resulting file
+   are trusted and have been reviewed. pycodify does not make ``exec`` safe for
+   untrusted input.
+
+Replay compatibility is owned jointly by the generated imports and the APIs
+they call. Explicit mode records default-valued fields, but neither mode can
+guarantee replay across incompatible module moves or constructor changes.

{pycodify-0.1.2 → pycodify-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycodify"
-version = "0.1.2"
+version = "0.2.0"
 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"}
@@ -62,11 +62,11 @@ target-version = ["py310", "py311", "py312", "py313"]
 
 [tool.ruff]
 line-length = 100
-target-version = "0.1.2"
+target-version = "py310"
 select = ["E", "F", "I", "N", "W", "UP"]
 
 [tool.mypy]
-python_version = "0.1.2"
+python_version = "3.10"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true

{pycodify-0.1.2 → pycodify-0.2.0}/src/pycodify/__init__.py

@@ -1,20 +1,23 @@
+# 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 .imports import resolve_imports
+from .paths import PathCollector, PathConstructor, PathFactoring
 
-# Register default formatters
-from . import formatters as _formatters  # noqa: F401
-
-__version__ = "0.1.2"
+__version__ = "0.2.0"
 
 __all__ = [
     "Assignment",
@@ -22,9 +25,15 @@ __all__ = [
     "CodeBlock",
     "Comment",
     "FormatContext",
+    "PathCollector",
+    "PathConstructor",
+    "PathFactoring",
+    "PathRendering",
+    "PythonSourceLiteral",
     "SourceFormatter",
     "SourceFragment",
     "generate_python_source",
+    "imported_name",
     "resolve_imports",
     "to_source",
 ]