pycodify 0.1.0__tar.gz

pycodify-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,102 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master, claude/**]
+  pull_request:
+    branches: [main, master]
+  workflow_dispatch:
+
+jobs:
+  # Test across Python versions and OSes
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests with coverage
+        run: |
+          pytest --cov=src/pycodify --cov-report=xml --cov-report=html --cov-report=term-missing -v
+
+      - name: Upload coverage to Codecov
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v3
+        with:
+          file: ./coverage.xml
+          fail_ci_if_error: false
+
+  # Code quality checks
+  code-quality:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff black mypy
+
+      - name: Run ruff (linting)
+        run: |
+          ruff check src/ --output-format=github
+
+      - name: Run black (formatting check)
+        run: |
+          black --check src/
+
+      - name: Run mypy (type checking)
+        run: |
+          mypy src/ --ignore-missing-imports
+
+  # Documentation build check
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Build documentation
+        run: |
+          cd docs
+          make html
+
+      - name: Check for build warnings
+        run: |
+          cd docs
+          make html SPHINXOPTS="-W --keep-going"
+

pycodify-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+  id-token: write  # Required for trusted publishing
+
+jobs:
+  build-and-publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pycodify
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check distribution
+        run: |
+          pip install twine
+          twine check dist/*
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+

pycodify-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.pytest_cache/
+.coverage
+.dist-info/
+.build/
+.eggs/

pycodify-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,134 @@
+# Contributing to pycodify
+
+Thank you for your interest in contributing to pycodify! This document provides guidelines for development, testing, and submission.
+
+## Development Setup
+
+### Prerequisites
+- Python 3.10+
+- Git
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/OpenHCSDev/pycodify.git
+cd pycodify
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in development mode with all dependencies
+pip install -e ".[dev,docs]"
+```
+
+## Code Style
+
+pycodify follows strict code quality standards:
+
+### Formatting
+- **Black**: Code formatting (line length: 100)
+- **Ruff**: Linting and import sorting
+- **MyPy**: Static type checking
+
+```bash
+# Format code
+black src/ tests/
+
+# Lint
+ruff check src/ tests/
+
+# Type check
+mypy src/
+```
+
+### Docstrings
+- Use Google-style docstrings
+- Include type hints in function signatures
+- Document all public APIs
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run with coverage
+pytest tests/ --cov=src/pycodify --cov-report=html
+
+# Run specific test file
+pytest tests/test_core.py -v
+```
+
+### Test Requirements
+- Minimum 80% code coverage
+- All tests must pass before submission
+- Use pytest fixtures for setup/teardown
+- Test both collection and regeneration passes
+
+## Submitting Changes
+
+### Before Submitting
+1. Ensure all tests pass: `pytest tests/`
+2. Format code: `black src/ tests/`
+3. Run linter: `ruff check src/ tests/`
+4. Type check: `mypy src/`
+5. Update documentation if needed
+
+### Pull Request Process
+1. Create a feature branch: `git checkout -b feature/your-feature`
+2. Make your changes with clear commit messages
+3. Push to your fork and create a Pull Request
+4. Ensure CI/CD checks pass
+5. Request review from maintainers
+
+### Commit Message Format
+```
+<type>: <subject>
+
+<body>
+
+<footer>
+```
+
+Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+## Documentation
+
+### Building Docs Locally
+
+```bash
+cd docs
+make html
+# Open build/html/index.html in browser
+```
+
+### Documentation Standards
+- Update README.md for user-facing changes
+- Update docstrings for API changes
+- Add examples for new features
+- Document the two-pass algorithm for custom formatters
+
+## Architecture Notes
+
+pycodify uses a two-pass algorithm:
+1. **Collection Pass**: Traverse object, emit code fragments, collect imports
+2. **Resolution Pass**: Detect collisions, generate aliases, regenerate code
+
+Custom formatters should inherit from `SourceFormatter` and implement:
+- `can_format(value)`: Check if formatter handles this type
+- `format(value, context)`: Return SourceFragment with code and imports
+
+## Questions?
+
+- Open an issue for bugs or feature requests
+- Check existing issues before creating new ones
+- Use discussions for questions
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.
+

pycodify-0.1.0/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.

pycodify-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,54 @@
+# 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/docs/Makefile

@@ -0,0 +1,18 @@
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

pycodify-0.1.0/docs/api.rst

@@ -0,0 +1,106 @@
+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.0/docs/architecture.rst

@@ -0,0 +1,89 @@
+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:
+
+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
+
+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:
+           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]))
+
+Priority-based dispatch selects the most specific formatter. Domain extensions add formatters without modifying core code.
+
+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 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.
+
+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.
+
+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)
+- **imports.py**: Import resolution and collision handling
+