pycodify 0.1.0__py3-none-any.whl

pycodify/__init__.py

@@ -0,0 +1,30 @@
+from .core import (
+    Assignment,
+    BlankLine,
+    CodeBlock,
+    Comment,
+    FormatContext,
+    SourceFormatter,
+    SourceFragment,
+    generate_python_source,
+    to_source,
+)
+from .imports import resolve_imports
+
+# Register default formatters
+from . import formatters as _formatters  # noqa: F401
+
+__version__ = "0.1.1"
+
+__all__ = [
+    "Assignment",
+    "BlankLine",
+    "CodeBlock",
+    "Comment",
+    "FormatContext",
+    "SourceFormatter",
+    "SourceFragment",
+    "generate_python_source",
+    "resolve_imports",
+    "to_source",
+]

pycodify/core.py

@@ -0,0 +1,145 @@
+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
+
+
+@dataclass(frozen=True)
+class SourceFragment:
+    """Result of serializing a value to Python source."""
+
+    code: str
+    imports: FrozenSet[Tuple[str, str]] = frozenset()
+
+    def __add__(self, other: "SourceFragment") -> "SourceFragment":
+        return SourceFragment(
+            code=self.code + other.code,
+            imports=self.imports | other.imports,
+        )
+
+
+@dataclass
+class FormatContext:
+    """Context passed through serialization."""
+
+    indent: int = 0
+    clean_mode: bool = False
+    name_mappings: Dict[Tuple[str, str], str] = field(default_factory=dict)
+
+    def indented(self) -> "FormatContext":
+        return replace(self, indent=self.indent + 1)
+
+    @property
+    def indent_str(self) -> str:
+        return "    " * self.indent
+
+
+@dataclass(frozen=True)
+class Comment:
+    text: str
+
+
+@dataclass(frozen=True)
+class BlankLine:
+    pass
+
+
+@dataclass(frozen=True)
+class Assignment:
+    name: str
+    value: Any
+
+
+@dataclass(frozen=True)
+class CodeBlock:
+    items: Tuple[Any, ...]
+
+    @classmethod
+    def from_items(cls, items: Iterable[Any]) -> "CodeBlock":
+        return cls(tuple(items))
+
+
+class SourceFormatter(ABC):
+    """Formats a value to Python source code."""
+
+    priority: int = 0
+
+    _registry: ClassVar[List["SourceFormatter"]] = []
+    _sorted_registry: ClassVar[List["SourceFormatter"]] = []
+    _registry_dirty: ClassVar[bool] = False
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        if getattr(cls, "__abstract__", False):
+            return
+        SourceFormatter._registry.append(cls())
+        SourceFormatter._registry_dirty = True
+
+    @abstractmethod
+    def can_format(self, value: Any) -> bool:
+        """Return True if this formatter handles this value type."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def format(self, value: Any, context: FormatContext) -> SourceFragment:
+        """Format value to Python source, returning code and required imports."""
+        raise NotImplementedError
+
+    @classmethod
+    def register(cls, formatter: "SourceFormatter") -> None:
+        cls._registry.append(formatter)
+        cls._registry_dirty = True
+
+    @classmethod
+    def _iter_registry(cls) -> List["SourceFormatter"]:
+        if cls._registry_dirty:
+            cls._sorted_registry = sorted(
+                cls._registry,
+                key=lambda fmt: fmt.priority,
+                reverse=True,
+            )
+            cls._registry_dirty = False
+        return cls._sorted_registry
+
+    @classmethod
+    def get_formatter(cls, value: Any) -> "SourceFormatter":
+        for formatter in cls._iter_registry():
+            if formatter.can_format(value):
+                return formatter
+        raise TypeError(f"No formatter for {type(value)}")
+
+
+def to_source(value: Any, ctx: FormatContext | None = None) -> SourceFragment:
+    """Convert any value to Python source code."""
+    if isinstance(value, SourceFragment):
+        return value
+    ctx = ctx or FormatContext()
+    formatter = SourceFormatter.get_formatter(value)
+    return formatter.format(value, ctx)
+
+
+def generate_python_source(obj: Any, header: str = "", clean_mode: bool = False) -> str:
+    """Generate complete Python source with imports."""
+    from .imports import resolve_imports
+
+    ctx = 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)
+    fragment = to_source(obj, ctx)
+
+    code_lines: List[str] = []
+    if header:
+        code_lines.extend(header.splitlines())
+        code_lines.append("")
+    if import_lines:
+        code_lines.extend(import_lines)
+        code_lines.append("")
+
+    if fragment.code:
+        code_lines.append(fragment.code)
+
+    return "\n".join(code_lines)

pycodify/formatters.py

@@ -0,0 +1,348 @@
+from __future__ import annotations
+
+import dataclasses
+import typing
+from dataclasses import is_dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any, Tuple
+
+from .core import (
+    Assignment,
+    BlankLine,
+    CodeBlock,
+    Comment,
+    FormatContext,
+    SourceFormatter,
+    SourceFragment,
+    to_source,
+)
+
+
+class CommentFormatter(SourceFormatter):
+    priority = 100
+
+    def can_format(self, value: Any) -> bool:
+        return isinstance(value, Comment)
+
+    def format(self, value: Comment, context: FormatContext) -> SourceFragment:
+        text = value.text.strip()
+        if not text:
+            code = "#"
+        elif text.lstrip().startswith("#"):
+            code = text
+        else:
+            code = f"# {text}"
+        return SourceFragment(f"{context.indent_str}{code}", frozenset())
+
+
+class BlankLineFormatter(SourceFormatter):
+    priority = 100
+
+    def can_format(self, value: Any) -> bool:
+        return isinstance(value, BlankLine)
+
+    def format(self, value: BlankLine, context: FormatContext) -> SourceFragment:
+        return SourceFragment("", frozenset())
+
+
+class AssignmentFormatter(SourceFormatter):
+    priority = 90
+
+    def can_format(self, value: Any) -> bool:
+        return isinstance(value, Assignment)
+
+    def format(self, value: Assignment, context: FormatContext) -> SourceFragment:
+        fragment = to_source(value.value, context)
+        code = f"{context.indent_str}{value.name} = {fragment.code}"
+        return SourceFragment(code, fragment.imports)
+
+
+class CodeBlockFormatter(SourceFormatter):
+    priority = 80
+
+    def can_format(self, value: Any) -> bool:
+        return isinstance(value, CodeBlock)
+
+    def format(self, value: CodeBlock, context: FormatContext) -> SourceFragment:
+        codes = []
+        imports = set()
+        for item in value.items:
+            fragment = to_source(item, context)
+            imports |= fragment.imports
+            codes.append(fragment.code)
+        return SourceFragment("\n".join(codes), frozenset(imports))
+
+
+class EnumFormatter(SourceFormatter):
+    priority = 70
+
+    def can_format(self, value: Any) -> bool:
+        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]))
+
+
+class PathFormatter(SourceFormatter):
+    priority = 70
+
+    def can_format(self, value: Any) -> bool:
+        return isinstance(value, Path)
+
+    def format(self, value: Path, context: FormatContext) -> SourceFragment:
+        import_pair = ("pathlib", "Path")
+        name = context.name_mappings.get(import_pair, "Path")
+        return SourceFragment(f"{name}({repr(str(value))})", frozenset([import_pair]))
+
+
+class StrFormatter(SourceFormatter):
+    priority = 60
+
+    def can_format(self, value: Any) -> bool:
+        return isinstance(value, str)
+
+    def format(self, value: str, context: FormatContext) -> SourceFragment:
+        return SourceFragment(repr(value), frozenset())
+
+
+class LiteralFormatter(SourceFormatter):
+    priority = 50
+
+    def can_format(self, value: Any) -> bool:
+        return value is None or isinstance(value, (bool, int, float))
+
+    def format(self, value: Any, context: FormatContext) -> SourceFragment:
+        return SourceFragment(repr(value), frozenset())
+
+
+class CallableFormatter(SourceFormatter):
+    priority = 40
+
+    def can_format(self, value: Any) -> bool:
+        return callable(value) and not isinstance(value, type)
+
+    def format(self, value: Any, context: FormatContext) -> SourceFragment:
+        import_pair = (value.__module__, value.__name__)
+        name = context.name_mappings.get(import_pair, value.__name__)
+        return SourceFragment(name, frozenset([import_pair]))
+
+
+class ListFormatter(SourceFormatter):
+    priority = 30
+
+    def can_format(self, value: Any) -> bool:
+        return isinstance(value, list)
+
+    def format(self, value: list, context: FormatContext) -> SourceFragment:
+        if not value:
+            return SourceFragment("[]", frozenset())
+
+        item_ctx = context.indented()
+        item_frags = [to_source(item, item_ctx) for item in value]
+        imports = frozenset().union(*(frag.imports for frag in item_frags))
+        inner = f",\n{item_ctx.indent_str}".join(frag.code for frag in item_frags)
+        code = f"[\n{item_ctx.indent_str}{inner}\n{context.indent_str}]"
+        return SourceFragment(code, imports)
+
+
+class TupleFormatter(SourceFormatter):
+    priority = 30
+
+    def can_format(self, value: Any) -> bool:
+        return isinstance(value, tuple)
+
+    def format(self, value: tuple, context: FormatContext) -> SourceFragment:
+        if not value:
+            return SourceFragment("()", frozenset())
+
+        item_ctx = context.indented()
+        item_frags = [to_source(item, item_ctx) for item in value]
+        imports = frozenset().union(*(frag.imports for frag in item_frags))
+        inner = f",\n{item_ctx.indent_str}".join(frag.code for frag in item_frags)
+        if len(value) == 1:
+            inner = f"{inner},"
+        code = f"(\n{item_ctx.indent_str}{inner}\n{context.indent_str})"
+        return SourceFragment(code, imports)
+
+
+class DictFormatter(SourceFormatter):
+    priority = 30
+
+    def can_format(self, value: Any) -> bool:
+        return isinstance(value, dict)
+
+    def format(self, value: dict, context: FormatContext) -> SourceFragment:
+        if not value:
+            return SourceFragment("{}", frozenset())
+
+        item_ctx = context.indented()
+        entries = []
+        imports = set()
+        for key, val in value.items():
+            key_frag = to_source(key, item_ctx)
+            val_frag = to_source(val, item_ctx)
+            imports |= key_frag.imports
+            imports |= val_frag.imports
+            entries.append(f"{key_frag.code}: {val_frag.code}")
+
+        inner = f",\n{item_ctx.indent_str}".join(entries)
+        code = f"{{\n{item_ctx.indent_str}{inner}\n{context.indent_str}}}"
+        return SourceFragment(code, frozenset(imports))
+
+
+class SetFormatter(SourceFormatter):
+    priority = 30
+
+    def can_format(self, value: Any) -> bool:
+        return isinstance(value, set)
+
+    def format(self, value: set, context: FormatContext) -> SourceFragment:
+        if not value:
+            return SourceFragment("set()", frozenset())
+
+        item_ctx = context.indented()
+        item_frags = [to_source(item, item_ctx) for item in value]
+        imports = frozenset().union(*(frag.imports for frag in item_frags))
+        inner = f",\n{item_ctx.indent_str}".join(frag.code for frag in item_frags)
+        code = f"{{\n{item_ctx.indent_str}{inner}\n{context.indent_str}}}"
+        return SourceFragment(code, imports)
+
+
+class DataclassFormatter(SourceFormatter):
+    priority = 35
+
+    def can_format(self, value: Any) -> bool:
+        return is_dataclass(value) and not isinstance(value, type)
+
+    def format(self, value: Any, context: FormatContext) -> SourceFragment:
+        code, imports, _ = _format_dataclass_expression(value, context)
+        return SourceFragment(code, frozenset(imports))
+
+
+def _resolve_dataclass_class_from_type(field_type: Any) -> Any | None:
+    if field_type is None:
+        return None
+
+    origin = typing.get_origin(field_type)
+    if origin is typing.Union:
+        for arg in typing.get_args(field_type):
+            if arg is type(None):
+                continue
+            resolved = _resolve_dataclass_class_from_type(arg)
+            if resolved:
+                return resolved
+        return None
+
+    if isinstance(field_type, type) and dataclasses.is_dataclass(field_type):
+        return field_type
+
+    return None
+
+
+def _create_placeholder_dataclass_instance(dataclass_cls: type) -> Any:
+    instance = object.__new__(dataclass_cls)
+    for dc_field in dataclasses.fields(dataclass_cls):
+        object.__setattr__(instance, dc_field.name, None)
+
+    if hasattr(dataclass_cls, "_is_lazy_dataclass"):
+        object.__setattr__(instance, "_is_lazy_dataclass", True)
+
+    return instance
+
+
+def _create_default_instance(instance: Any) -> Any:
+    if hasattr(instance, "_resolve_field_value"):
+        default_instance = object.__new__(instance.__class__)
+        for dc_field in dataclasses.fields(instance):
+            object.__setattr__(default_instance, dc_field.name, None)
+        if hasattr(instance.__class__, "_is_lazy_dataclass"):
+            object.__setattr__(default_instance, "_is_lazy_dataclass", True)
+        return default_instance
+
+    try:
+        return instance.__class__()
+    except Exception:
+        default_instance = object.__new__(instance.__class__)
+        for dc_field in dataclasses.fields(instance):
+            if dc_field.default is not dataclasses.MISSING:
+                value = dc_field.default
+            elif dc_field.default_factory is not dataclasses.MISSING:  # type: ignore
+                value = dc_field.default_factory()  # type: ignore
+            else:
+                value = None
+            object.__setattr__(default_instance, dc_field.name, value)
+        return default_instance
+
+
+def _format_dataclass_expression(
+    instance: Any,
+    context: FormatContext,
+) -> Tuple[str, set[Tuple[str, str]], bool]:
+    cls = instance.__class__
+    import_pair = (cls.__module__, cls.__name__)
+    class_name = context.name_mappings.get(import_pair, cls.__name__)
+    imports: set[Tuple[str, str]] = {import_pair}
+
+    default_instance = _create_default_instance(instance)
+
+    try:
+        type_hints = typing.get_type_hints(instance.__class__)
+    except Exception:
+        type_hints = {}
+
+    lines: list[str] = []
+    field_ctx = context.indented()
+
+    for dc_field in dataclasses.fields(instance):
+        field_name = dc_field.name
+
+        if hasattr(instance, "_resolve_field_value"):
+            current_value = object.__getattribute__(instance, field_name)
+            default_value = object.__getattribute__(default_instance, field_name)
+        else:
+            current_value = getattr(instance, field_name)
+            default_value = getattr(default_instance, field_name)
+
+        if (not context.clean_mode) and current_value is None:
+            field_type = type_hints.get(field_name, dc_field.type)
+            dataclass_cls = _resolve_dataclass_class_from_type(field_type)
+            if dataclass_cls is not None:
+                current_value = _create_placeholder_dataclass_instance(dataclass_cls)
+
+        if context.clean_mode and current_value == default_value:
+            continue
+
+        if dataclasses.is_dataclass(current_value) and not isinstance(current_value, type):
+            nested_code, nested_imports, nested_has_fields = _format_dataclass_expression(
+                current_value,
+                field_ctx,
+            )
+            if context.clean_mode and not nested_has_fields:
+                continue
+            imports |= nested_imports
+            lines.append(f"{field_name}={nested_code}")
+        else:
+            frag = to_source(current_value, field_ctx)
+            imports |= frag.imports
+            lines.append(f"{field_name}={frag.code}")
+
+    if not lines:
+        return f"{class_name}()", imports, False
+
+    inner = f",\n{field_ctx.indent_str}".join(lines)
+    code = f"{class_name}(\n{field_ctx.indent_str}{inner}\n{context.indent_str})"
+    return code, imports, True
+
+
+class FallbackFormatter(SourceFormatter):
+    priority = -100
+
+    def can_format(self, value: Any) -> bool:
+        return True
+
+    def format(self, value: Any, context: FormatContext) -> SourceFragment:
+        return SourceFragment(repr(value), frozenset())

pycodify/imports.py

@@ -0,0 +1,36 @@
+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

pycodify-0.1.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: pycodify
+Version: 0.1.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
+Project-URL: Repository, https://github.com/OpenHCSDev/pycodify
+Project-URL: Issues, https://github.com/OpenHCSDev/pycodify/issues
+Author-email: Tristan Simas <tristan.simas@mail.mcgill.ca>
+License: MIT
+License-File: LICENSE
+Keywords: code-generation,configuration,python-source,reproducibility,serialization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
+Requires-Dist: sphinx>=7.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# pycodify
+
+Python source code as a serialization format with automatic import resolution.
+
+## Quick Start
+
+```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)
+```
+
+## Why Python Source?
+
+| Format | Diffable | Inspectable | Editable | Type-preserving | Cross-version |
+|--------|:--------:|:-----------:|:--------:|:---------------:|:-------------:|
+| pickle | ✗ | ✗ | ✗ | ✓ | ✗ |
+| JSON/YAML | ✓ | ✓ | ✓ | ✗ | ✓ |
+| Python source | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+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.
+
+## 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
+
+## Documentation
+
+Full documentation available at [pycodify.readthedocs.io](https://pycodify.readthedocs.io)
+
+## Installation
+
+```bash
+pip install pycodify
+```
+
+## License
+
+MIT

pycodify-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pycodify/__init__.py,sha256=gHiMGKUAfA2OXU1gBtMPqIQR6rUoZRiH9hLhHjruhf0,547
+pycodify/core.py,sha256=o4Fhpxx8QOFrXBSxhNLB6KweJbGeM1pR2oDxpYbCLuo,4065
+pycodify/formatters.py,sha256=Zm50i71UXX1lfiGqRz97-zXRrYBT8NcNA9cqAlrlW2k,11774
+pycodify/imports.py,sha256=QIClblhNdr8pTkBLjsVN0iFxVv39PYEwz3OkuggkwwI,1226
+pycodify-0.1.0.dist-info/METADATA,sha256=Y0iGtSeVCmkWb5a-U-zcby97W7WLAmUeWrVGPXxcM4s,3182
+pycodify-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pycodify-0.1.0.dist-info/licenses/LICENSE,sha256=QaLlb9Yy_FmAXOzvvTABEDPQ5n_M3ck1KaGmz_A6p2Y,1064
+pycodify-0.1.0.dist-info/RECORD,,

pycodify-0.1.0.dist-info/WHEEL

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

pycodify-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenHCS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.