pycodify 0.1.2__tar.gz → 0.1.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycodify
-Version: 0.1.2
+Version: 0.1.3
 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.1.3}/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.1.3/docs/api.rst

@@ -0,0 +1,32 @@
+API orientation
+===============
+
+``Assignment`` and ``CodeBlock``
+   Structured top-level source items.
+
+``generate_python_source(obj, header="", clean_mode=False, *, context=None)``
+   Generate complete executable source and required imports. A caller-supplied
+   ``FormatContext`` is retained across both render passes and owns clean mode.
+
+``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 typed formatting state and output records. ``FormatContext`` may
+   carry exact-type ``extensions`` and exposes them through ``extension(type)``.
+
+The canonical import surface is ``pycodify.__all__``.
+
+Public API
+----------
+
+.. automodule:: pycodify
+   :members:
+   :member-order: bysource

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

@@ -8,9 +8,12 @@ Generating executable source requires knowing import aliases before emitting cod
 
 pycodify solves this with two passes:
 
-1. **Collection Pass**: Traverse the object, emit code fragments, collect ``(module, name)`` import pairs
-2. **Resolution**: Detect collisions (same name, different modules), generate deterministic aliases
-3. **Regeneration Pass**: Re-traverse with resolved ``name_mappings``, emit final code
+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``.
 
@@ -45,13 +48,39 @@ Core Components
   Represents a piece of generated code with its required imports.
 
 **FormatContext**
-  Carries state during formatting: ``name_mappings``, ``visited_objects``, etc.
-
-**ImportResolver**
-  Detects collisions and generates deterministic aliases for imports.
-
-**SourceGenerator**
-  Orchestrates the two-pass algorithm and produces final executable code.
+  Carries indentation depth, ``clean_mode``, the ``(module, name)`` to
+  local-name mapping, and caller-owned typed extensions. ``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.
+
+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.
+
+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.
 
 Clean Mode
 ----------
@@ -64,6 +93,20 @@ Clean mode omits fields matching their default values. This requires:
 
 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.
+
 Lazy Dataclass Integration
 ---------------------------
 
@@ -86,4 +129,3 @@ Module Structure
 - **core.py**: Main API (``Assignment``, ``generate_python_source``)
 - **formatters.py**: Built-in formatters (dataclass, enum, primitive types)
 - **imports.py**: Import resolution and collision handling
-

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

@@ -1,16 +1,17 @@
 """Sphinx configuration for pycodify."""
 import os
 import sys
+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"
+version = "0.1"
+release = "0.1.3"
 
 # General configuration
 extensions = [
@@ -54,7 +55,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 +70,3 @@ html_favicon = None
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
 }
-

pycodify-0.1.3/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.1.3/docs/usage.rst

@@ -0,0 +1,226 @@
+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.
+
+Typed rendering extensions
+--------------------------
+
+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:
+
+.. code-block:: python
+
+   from dataclasses import dataclass
+   from types import MappingProxyType
+
+   from pycodify import (
+       Assignment,
+       FormatContext,
+       SourceFormatter,
+       SourceFragment,
+       generate_python_source,
+   )
+
+   @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'"
+
+``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.
+
+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.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycodify"
-version = "0.1.2"
+version = "0.1.3"
 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.1.3}/src/pycodify/__init__.py

@@ -14,7 +14,7 @@ from .imports import resolve_imports
 # Register default formatters
 from . import formatters as _formatters  # noqa: F401
 
-__version__ = "0.1.2"
+__version__ = "0.1.3"
 
 __all__ = [
     "Assignment",

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

@@ -2,7 +2,9 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field, replace
-from typing import Any, ClassVar, Dict, FrozenSet, Iterable, List, Tuple
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any, ClassVar, FrozenSet, Iterable, List, Tuple
 
 
 @dataclass(frozen=True)
@@ -19,13 +21,18 @@ class SourceFragment:
         )
 
 
-@dataclass
+@dataclass(frozen=True)
 class FormatContext:
     """Context passed through serialization."""
 
     indent: int = 0
     clean_mode: bool = False
-    name_mappings: Dict[Tuple[str, str], str] = field(default_factory=dict)
+    name_mappings: Mapping[Tuple[str, str], str] = field(
+        default_factory=lambda: MappingProxyType({})
+    )
+    extensions: Mapping[type[object], object] = field(
+        default_factory=lambda: MappingProxyType({})
+    )
 
     def indented(self) -> "FormatContext":
         return replace(self, indent=self.indent + 1)
@@ -34,6 +41,11 @@ class FormatContext:
     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)
+
 
 @dataclass(frozen=True)
 class Comment:
@@ -119,16 +131,22 @@ def to_source(value: Any, ctx: FormatContext | None = None) -> SourceFragment:
     return formatter.format(value, ctx)
 
 
-def generate_python_source(obj: Any, header: str = "", clean_mode: bool = False) -> str:
+def generate_python_source(
+    obj: Any,
+    header: str = "",
+    clean_mode: bool = False,
+    *,
+    context: FormatContext | None = None,
+) -> str:
     """Generate complete Python source with imports."""
     from .imports import resolve_imports
 
-    ctx = FormatContext(clean_mode=clean_mode)
+    ctx = context or FormatContext(clean_mode=clean_mode)
     fragment = to_source(obj, ctx)
 
     import_lines, name_mappings = resolve_imports(fragment.imports)
 
-    ctx = FormatContext(clean_mode=clean_mode, name_mappings=name_mappings)
+    ctx = replace(ctx, name_mappings=MappingProxyType(name_mappings))
     fragment = to_source(obj, ctx)
 
     code_lines: List[str] = []

{pycodify-0.1.2 → pycodify-0.1.3}/src/pycodify/formatters.py

@@ -317,6 +317,13 @@ def _format_dataclass_expression(
             continue
 
         if dataclasses.is_dataclass(current_value) and not isinstance(current_value, type):
+            formatter = SourceFormatter.get_formatter(current_value)
+            if not isinstance(formatter, DataclassFormatter):
+                frag = formatter.format(current_value, field_ctx)
+                imports |= frag.imports
+                lines.append(f"{field_name}={frag.code}")
+                continue
+
             nested_code, nested_imports, nested_has_fields = _format_dataclass_expression(
                 current_value,
                 field_ctx,

pycodify-0.1.3/src/pycodify/imports.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Dict, FrozenSet, Iterable, List, Optional, Tuple
+
+
+ImportSpec = Tuple[str, Optional[str]]
+
+
+def _alias_for_collision(name: str, module: str) -> str:
+    return f"{name}_{module.replace('.', '_')}"
+
+
+def _format_import_target(name: str, alias: Optional[str]) -> str:
+    if alias is None:
+        return name
+    return f"{name} as {alias}"
+
+
+def _format_module_import(module: str, targets: List[ImportSpec]) -> List[str]:
+    if len(targets) == 1:
+        name, alias = targets[0]
+        return [f"from {module} import {_format_import_target(name, alias)}"]
+
+    lines = [f"from {module} import ("]
+    lines.extend(
+        f"    {_format_import_target(name, alias)},"
+        for name, alias in targets
+    )
+    lines.append(")")
+    return lines
+
+
+def resolve_imports(
+    imports: FrozenSet[Tuple[str, str]] | Iterable[Tuple[str, str]],
+) -> Tuple[List[str], Dict[Tuple[str, str], str]]:
+    """Resolve import collisions and generate import lines."""
+    import_pairs = {pair for pair in imports if pair and pair[0] and pair[1]}
+
+    # Filter out builtins and None modules
+    filtered = [
+        (module, name)
+        for module, name in import_pairs
+        if module not in (None, "builtins")
+    ]
+
+    name_to_modules = defaultdict(list)
+    for module, name in filtered:
+        name_to_modules[name].append(module)
+
+    imports_by_module: Dict[str, List[ImportSpec]] = defaultdict(list)
+    name_mappings: Dict[Tuple[str, str], str] = {}
+
+    for module, name in sorted(filtered):
+        if len(name_to_modules[name]) > 1:
+            alias = _alias_for_collision(name, module)
+            imports_by_module[module].append((name, alias))
+            name_mappings[(module, name)] = alias
+        else:
+            imports_by_module[module].append((name, None))
+            name_mappings[(module, name)] = name
+
+    import_lines: List[str] = []
+    for module in sorted(imports_by_module):
+        import_lines.extend(
+            _format_module_import(
+                module,
+                sorted(imports_by_module[module], key=lambda target: target[0]),
+            )
+        )
+
+    return import_lines, name_mappings

{pycodify-0.1.2 → pycodify-0.1.3}/tests/test_core.py

@@ -3,7 +3,15 @@
 import pytest
 from dataclasses import dataclass
 from enum import Enum
-from pycodify import Assignment, generate_python_source
+from types import MappingProxyType
+
+from pycodify import (
+    Assignment,
+    FormatContext,
+    SourceFormatter,
+    SourceFragment,
+    generate_python_source,
+)
 
 
 class Color(Enum):
@@ -21,6 +29,22 @@ class SimpleConfig:
     enabled: bool = True
 
 
+class ExtensionProbe:
+    pass
+
+
+class ExtensionProbeFormatter(SourceFormatter):
+    priority = 200
+
+    def can_format(self, value):
+        return isinstance(value, ExtensionProbe)
+
+    def format(self, value, context):
+        del value
+        marker = context.extension(ExtensionProbe)
+        return SourceFragment(repr(marker), frozenset())
+
+
 class TestBasicGeneration:
     """Test basic source code generation."""
 
@@ -77,6 +101,18 @@ class TestBasicGeneration:
         except Exception as e:
             pytest.fail(f"Generated source is not executable: {e}\n{source}")
 
+    def test_context_extensions_survive_both_render_passes(self):
+        context = FormatContext(
+            extensions=MappingProxyType({ExtensionProbe: "preserved"})
+        )
+
+        source = generate_python_source(
+            Assignment("value", ExtensionProbe()),
+            context=context,
+        )
+
+        assert source == "value = 'preserved'"
+
 
 class TestImportCollisions:
     """Test handling of import name collisions."""
@@ -91,4 +127,3 @@ class TestImportCollisions:
         
         assert source is not None
         assert len(source) > 0
-

pycodify-0.1.3/tests/test_imports.py

@@ -0,0 +1,53 @@
+"""Tests for pycodify import rendering."""
+
+from pycodify.imports import resolve_imports
+
+
+def test_resolve_imports_groups_multiple_names_from_same_module():
+    import_lines, name_mappings = resolve_imports(
+        frozenset(
+            {
+                ("example.module", "Beta"),
+                ("example.module", "Alpha"),
+                ("other.module", "Gamma"),
+            }
+        )
+    )
+
+    assert import_lines == [
+        "from example.module import (",
+        "    Alpha,",
+        "    Beta,",
+        ")",
+        "from other.module import Gamma",
+    ]
+    assert name_mappings == {
+        ("example.module", "Alpha"): "Alpha",
+        ("example.module", "Beta"): "Beta",
+        ("other.module", "Gamma"): "Gamma",
+    }
+
+
+def test_resolve_imports_groups_alias_collisions_with_module_imports():
+    import_lines, name_mappings = resolve_imports(
+        frozenset(
+            {
+                ("alpha.sources", "Config"),
+                ("beta.sources", "Config"),
+                ("alpha.sources", "Pipeline"),
+            }
+        )
+    )
+
+    assert import_lines == [
+        "from alpha.sources import (",
+        "    Config as Config_alpha_sources,",
+        "    Pipeline,",
+        ")",
+        "from beta.sources import Config as Config_beta_sources",
+    ]
+    assert name_mappings == {
+        ("alpha.sources", "Config"): "Config_alpha_sources",
+        ("alpha.sources", "Pipeline"): "Pipeline",
+        ("beta.sources", "Config"): "Config_beta_sources",
+    }

pycodify-0.1.2/docs/api.rst

@@ -1,106 +0,0 @@
-API Reference
-=============
-
-Core API
---------
-
-.. automodule:: pycodify.core
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Formatters
-----------
-
-.. automodule:: pycodify.formatters
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Import Resolution
------------------
-
-.. automodule:: pycodify.imports
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-Main Functions
---------------
-
-.. py:function:: generate_python_source(assignment: Assignment, clean_mode: bool = True) -> str
-
-   Generate executable Python source code from an object.
-
-   :param assignment: Assignment object specifying variable name and value
-   :type assignment: Assignment
-   :param clean_mode: If True, omit fields matching defaults. If False, include all fields.
-   :type clean_mode: bool
-   :return: Executable Python source code with imports
-   :rtype: str
-
-   **Example:**
-
-   .. code-block:: python
-
-      from pycodify import Assignment, generate_python_source
-      from dataclasses import dataclass
-
-      @dataclass
-      class Config:
-          name: str = "default"
-          value: int = 42
-
-      config = Config(name="production", value=100)
-      code = generate_python_source(Assignment("config", config))
-      print(code)
-
-.. py:class:: Assignment
-
-   Represents a variable assignment for code generation.
-
-   .. py:method:: __init__(name: str, value: Any)
-
-      Create an assignment.
-
-      :param name: Variable name
-      :type name: str
-      :param value: Value to serialize
-      :type value: Any
-
-.. py:class:: SourceFormatter
-
-   Base class for custom formatters.
-
-   .. py:method:: can_format(value: Any) -> bool
-
-      Check if this formatter can handle the value.
-
-      :param value: Value to check
-      :type value: Any
-      :return: True if this formatter can format the value
-      :rtype: bool
-
-   .. py:method:: format(value: Any, context: FormatContext) -> SourceFragment
-
-      Format a value to source code.
-
-      :param value: Value to format
-      :type value: Any
-      :param context: Formatting context with state
-      :type context: FormatContext
-      :return: Source code fragment with imports
-      :rtype: SourceFragment
-
-.. py:class:: SourceFragment
-
-   Represents generated source code with its imports.
-
-   .. py:attribute:: code
-
-      The generated Python source code.
-
-   .. py:attribute:: imports
-
-      Set of (module, name) tuples required for the code.
-

pycodify-0.1.2/docs/index.rst

@@ -1,72 +0,0 @@
-pycodify Documentation
-======================
-
-**pycodify** serializes Python objects to executable Python source code with automatic import resolution.
-
-The key insight: **Python source code is a serialization format.** Rather than inventing a format and writing loaders, pycodify emits code that Python itself interprets. The import system becomes the deserializer.
-
-Quick Start
------------
-
-.. code-block:: python
-
-   from pycodify import Assignment, generate_python_source
-   from dataclasses import dataclass
-
-   @dataclass
-   class Config:
-       name: str = "default"
-       value: int = 42
-
-   config = Config(name="production", value=100)
-   code = generate_python_source(Assignment("config", config), clean_mode=True)
-   print(code)
-   # Output:
-   # from __main__ import Config
-   # config = Config(name='production', value=100)
-
-Features
---------
-
-- **Complete Executable Source**: Generates imports + code, not just expressions
-- **Type-Preserving**: Enums, Paths, callables serialize as themselves
-- **Collision Handling**: Automatic aliasing for name collisions across modules
-- **Clean Mode**: Omit fields matching defaults for concise output
-- **Extensible**: Register custom formatters for domain-specific types
-
-Why Python Source?
-------------------
-
-| Format | Diffable | Inspectable | Editable | Type-preserving | Cross-version |
-|--------|:--------:|:-----------:|:--------:|:---------------:|:-------------:|
-| pickle | ✗ | ✗ | ✗ | ✓ | ✗ |
-| JSON/YAML | ✓ | ✓ | ✓ | ✗ | ✓ |
-| Python source | ✓ | ✓ | ✓ | ✓ | ✓ |
-
-Contents
---------
-
-.. toctree::
-   :maxdepth: 2
-
-   usage
-   api
-   architecture
-
-API Reference
--------------
-
-.. autosummary::
-   :toctree: _autosummary
-
-   pycodify.core
-   pycodify.formatters
-   pycodify.imports
-
-Indices and Tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

pycodify-0.1.2/docs/usage.rst

@@ -1,129 +0,0 @@
-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** (default) omits fields that match their default values:
-
-.. 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:
-
-.. 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 have classes with the same name, pycodify automatically aliases them:
-
-.. code-block:: python
-
-   from module_a import Config as ConfigA
-   from module_b import Config as ConfigB
-
-   # pycodify detects the collision and generates:
-   # from module_a import Config as Config_1
-   # from module_b import Config as Config_2
-   # obj = Config_1(...)
-
-Nested Dataclasses
--------------------
-
-Nested dataclasses are properly serialized with all necessary imports:
-
-.. code-block:: python
-
-   @dataclass
-   class DatabaseConfig:
-       host: str = "localhost"
-       port: int = 5432
-
-   @dataclass
-   class AppConfig:
-       database: DatabaseConfig = 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
-

pycodify-0.1.2/src/pycodify/imports.py

@@ -1,36 +0,0 @@
-from __future__ import annotations
-
-from collections import defaultdict
-from typing import Dict, FrozenSet, Iterable, List, Tuple
-
-
-def resolve_imports(
-    imports: FrozenSet[Tuple[str, str]] | Iterable[Tuple[str, str]],
-) -> Tuple[List[str], Dict[Tuple[str, str], str]]:
-    """Resolve import collisions and generate import lines."""
-    import_pairs = {pair for pair in imports if pair and pair[0] and pair[1]}
-
-    # Filter out builtins and None modules
-    filtered = [
-        (module, name)
-        for module, name in import_pairs
-        if module not in (None, "builtins")
-    ]
-
-    name_to_modules = defaultdict(list)
-    for module, name in filtered:
-        name_to_modules[name].append(module)
-
-    import_lines: List[str] = []
-    name_mappings: Dict[Tuple[str, str], str] = {}
-
-    for module, name in sorted(filtered):
-        if len(name_to_modules[name]) > 1:
-            alias = f"{name}_{module.split('.')[-1]}"
-            import_lines.append(f"from {module} import {name} as {alias}")
-            name_mappings[(module, name)] = alias
-        else:
-            import_lines.append(f"from {module} import {name}")
-            name_mappings[(module, name)] = name
-
-    return import_lines, name_mappings