objectstate 1.0.0__tar.gz

objectstate-1.0.0/.github/badges/coverage.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 30.32%"><title>coverage: 30.32%</title><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#e05d44"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text aria-hidden="true" x="315" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="510">coverage</text><text x="315" y="140" transform="scale(.1)" fill="#fff" textLength="510">coverage</text><text aria-hidden="true" x="865" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">30.32%</text><text x="865" y="140" transform="scale(.1)" fill="#fff" textLength="430">30.32%</text></g></svg>

objectstate-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,101 @@
+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.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=hieraconf --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"

objectstate-1.0.0/.github/workflows/coverage-pages.yml

@@ -0,0 +1,118 @@
+name: Tests, Coverage and GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write  # Needed for badge commit
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  test-and-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    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 ".[dev]"
+          pip install genbadge[coverage]
+
+      - name: Run tests with coverage
+        # Continue even if tests fail - we want coverage reports regardless
+        # This workflow is for reporting only; the CI workflow enforces test success
+        continue-on-error: true
+        run: |
+          mkdir -p site
+          python -m pytest --cov=hieraconf \
+                --cov-report=xml \
+                --cov-report=html:site/coverage \
+                tests/
+
+      - name: Generate coverage badge
+        run: |
+          mkdir -p .github/badges
+          genbadge coverage -i coverage.xml -o .github/badges/coverage.svg
+
+      - name: Create index.html and README
+        run: |
+          # Create index.html for redirection
+          cat > site/index.html << 'EOF'
+          <!DOCTYPE html>
+          <html>
+            <head>
+              <meta http-equiv="refresh" content="0; url=./coverage/">
+              <title>Redirecting to coverage report...</title>
+            </head>
+            <body>
+              <p>Redirecting to coverage report... <a href="./coverage/">Click here if not redirected</a></p>
+            </body>
+          </html>
+          EOF
+
+          # Create README.md in the site directory
+          cat > site/README.md << 'EOF'
+          # hieraconf Code Coverage Reports
+
+          This site contains the code coverage reports for the [hieraconf](https://github.com/trissim/hieraconf) project.
+
+          ## Navigation
+
+          - [Coverage Report](./coverage/): View the HTML coverage report
+
+          ## About
+
+          These reports are automatically generated by GitHub Actions whenever changes are pushed to the main branch.
+          They show the percentage of code that is covered by automated tests.
+          EOF
+
+      - name: Commit and push if coverage badge changed
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git add .github/badges/coverage.svg -f
+          # Only commit if there are changes
+          if git diff --staged --quiet; then
+            echo "No changes to coverage badge"
+          else
+            git commit -m "chore: update coverage badge [skip ci]"
+            git push
+          fi
+
+      - name: Check GitHub Pages status
+        run: |
+          echo "⚠️ IMPORTANT: Make sure GitHub Pages is enabled in your repository settings!"
+          echo "Go to https://github.com/trissim/hieraconf/settings/pages"
+          echo "Set 'Source' to 'GitHub Actions' to enable GitHub Pages deployment."
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'site'
+          retention-days: 1
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+        timeout-minutes: 10

objectstate-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+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/objectstate
+
+    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

objectstate-1.0.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Documentation
+docs/_build/
+site/
+
+# OS
+.DS_Store
+Thumbs.db

objectstate-1.0.0/.readthedocs.yaml

@@ -0,0 +1,20 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: false
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

objectstate-1.0.0/BADGE_SETUP.md

@@ -0,0 +1,94 @@
+# Badge and Documentation Setup
+
+This document explains the badges added to the README and the manual setup steps required.
+
+## Badges Added
+
+### 1. Read the Docs Badge
+```markdown
+[![Documentation Status](https://readthedocs.org/projects/objectstate/badge/?version=latest)](https://objectstate.readthedocs.io/en/latest/?badge=latest)
+```
+- **Status**: Should work automatically if objectstate is registered on ReadTheDocs
+- **Link**: https://objectstate.readthedocs.io
+- **Configuration**: `.readthedocs.yaml` is already configured
+
+### 2. Code Coverage Badge
+```markdown
+[![Coverage](https://raw.githubusercontent.com/trissim/objectstate/main/.github/badges/coverage.svg)](https://trissim.github.io/objectstate/coverage/)
+```
+- **Status**: Will be automatically updated by GitHub Actions workflow
+- **Link**: https://trissim.github.io/objectstate/coverage/
+- **Workflow**: `.github/workflows/coverage-pages.yml`
+
+## Manual Setup Required
+
+### 1. Enable GitHub Pages
+The coverage badge and reports require GitHub Pages to be enabled:
+
+1. Go to: https://github.com/trissim/objectstate/settings/pages
+2. Under "Build and deployment":
+   - **Source**: Select "GitHub Actions"
+3. Save the settings
+
+Once enabled, the coverage reports will be available at:
+- Badge SVG: https://raw.githubusercontent.com/trissim/objectstate/main/.github/badges/coverage.svg
+- Coverage Report: https://trissim.github.io/objectstate/coverage/
+
+### 2. Update Repository Description (Optional but Recommended)
+To match the problem statement requirement:
+
+1. Go to: https://github.com/trissim/objectstate
+2. Click the ⚙️ (settings) icon next to "About"
+3. Add or update:
+   - **Description**: Generic lazy dataclass configuration framework with dual-axis inheritance
+   - **Website**: https://objectstate.readthedocs.io
+   - **Topics**: Add relevant tags like `python`, `configuration`, `dataclass`, etc.
+4. Save changes
+
+### 3. Verify ReadTheDocs Integration
+Ensure the repository is properly linked to ReadTheDocs:
+
+1. Go to: https://readthedocs.org/dashboard/
+2. Verify `objectstate` project exists
+3. Check webhook is configured at: https://github.com/trissim/objectstate/settings/hooks
+4. Trigger a build to ensure documentation is up to date
+
+## How the Coverage Badge Works
+
+The coverage badge is similar to the ezstitcher repository setup:
+
+1. On every push to `main` branch, the `coverage-pages.yml` workflow:
+   - Runs tests with coverage
+   - Generates a coverage badge SVG at `.github/badges/coverage.svg`
+   - Commits the badge back to the repository
+   - Deploys HTML coverage reports to GitHub Pages
+
+2. The badge in README.md links to:
+   - SVG file from the `main` branch (always up-to-date)
+   - Coverage report hosted on GitHub Pages
+
+## Testing the Setup
+
+After enabling GitHub Pages:
+
+1. Push a commit to the `main` branch
+2. Wait for the "Tests, Coverage and GitHub Pages" workflow to complete
+3. Check that:
+   - The badge SVG was updated in `.github/badges/coverage.svg`
+   - The coverage report is available at https://trissim.github.io/objectstate/coverage/
+   - The badge in README shows the correct coverage percentage
+
+## Differences from Codecov
+
+This setup uses GitHub Pages for coverage reports instead of Codecov.io:
+
+**Advantages:**
+- No external service account required
+- No API tokens needed
+- Works out of the box
+- Reports hosted on your GitHub Pages
+
+**CI Workflow:**
+- The existing `ci.yml` workflow still uploads to Codecov if configured
+- The new `coverage-pages.yml` workflow generates the badge and GitHub Pages
+- Both can coexist - Codecov for CI checks, GitHub Pages for the badge

objectstate-1.0.0/DOCUMENTATION_AUDIT.md

@@ -0,0 +1,81 @@
+# ObjectState Documentation Audit
+
+## Summary
+Found **3 critical documentation bugs** in README.md where examples reference non-existent API methods.
+
+## Issues Found
+
+### ❌ Issue 1: `undo()` and `redo()` methods don't exist
+**Location**: README.md lines 124-125
+**Current (WRONG)**:
+```python
+ObjectStateRegistry.undo()
+ObjectStateRegistry.redo()
+```
+
+**Actual API**:
+```python
+ObjectStateRegistry.time_travel_back()  # Go one step back
+ObjectStateRegistry.time_travel_forward()  # Go one step forward
+```
+
+**Fix**: Replace with correct method names
+
+---
+
+### ❌ Issue 2: `get_branch_history()` returns Snapshot objects, not with `.id` attribute
+**Location**: README.md line 133
+**Current (CORRECT)**: `history = ObjectStateRegistry.get_branch_history()`
+**But line 134 is WRONG**:
+```python
+ObjectStateRegistry.time_travel_to_snapshot(history[5].id)
+```
+
+**Actual**: `Snapshot` objects DO have `.id` attribute ✓ (This is correct)
+
+---
+
+### ❌ Issue 3: Missing `atomic()` context manager documentation
+**Location**: README.md lines 128-130
+**Current**: Shows `atomic()` usage
+**Status**: ✓ CORRECT - `atomic()` method exists and works as documented
+
+---
+
+## Additional Findings
+
+### ✓ Correct API Methods (verified in code):
+- `ObjectStateRegistry.register(state)` ✓
+- `ObjectStateRegistry.unregister(state)` ✓
+- `ObjectStateRegistry.get_by_scope(scope_id)` ✓
+- `ObjectStateRegistry.get_all()` ✓
+- `state.update_parameter(field, value)` ✓
+- `state.save()` ✓
+- `state.restore_saved()` ✓
+- `ObjectStateRegistry.atomic(label)` ✓
+- `ObjectStateRegistry.get_branch_history()` ✓
+- `ObjectStateRegistry.time_travel_to_snapshot(id)` ✓
+- `ObjectStateRegistry.time_travel_to_head()` ✓
+- `ObjectStateRegistry.create_branch(name, description)` ✓
+- `ObjectStateRegistry.switch_branch(name)` ✓
+- `ObjectStateRegistry.list_branches()` ✓
+- `ObjectStateRegistry.export_history_to_dict()` ✓
+- `ObjectStateRegistry.import_history_from_dict(data)` ✓
+- `ObjectStateRegistry.save_history_to_file(path)` ✓
+- `ObjectStateRegistry.load_history_from_file(path)` ✓
+
+### ✓ ObjectState class methods (verified):
+- `state.dirty_fields` ✓
+- `state.save()` ✓
+- `state.restore_saved()` ✓
+- `state.update_parameter(field, value)` ✓
+
+## Recommended Fixes
+
+1. **Replace `undo()`/`redo()` with `time_travel_back()`/`time_travel_forward()`**
+2. **Add note about time-travel semantics** (not traditional undo/redo)
+3. **Consider adding convenience aliases** if backward compatibility needed
+
+## Status
+Ready for implementation
+