django-phase 0.1.0__tar.gz

django_phase-0.1.0/.ambient-package-update/metadata.py

@@ -0,0 +1,45 @@
+from ambient_package_update.metadata.author import PackageAuthor
+from ambient_package_update.metadata.constants import (
+    DEPLOYMENT_STATUS_BETA,
+    DEV_DEPENDENCIES,
+    LICENSE_MIT,
+    SUPPORTED_DJANGO_VERSIONS,
+    SUPPORTED_PYTHON_VERSIONS,
+)
+from ambient_package_update.metadata.maintainer import PackageMaintainer
+from ambient_package_update.metadata.package import PackageMetadata
+from ambient_package_update.metadata.readme import ReadmeContent
+
+METADATA = PackageMetadata(
+    package_name="django_phase",
+    module_name="phase",
+    github_package_group="beyonder-deutschland",
+    authors=[
+        PackageAuthor(
+            name="Beyonder Deutschland",
+            email="hello@beyonder.de",
+        ),
+    ],
+    maintainer=PackageMaintainer(name="Beyonder Deutschland", url="https://beyonder.de/", email="hello@beyonder.de"),
+    licenser="Beyonder Deutschland GmbH",
+    license=LICENSE_MIT,
+    license_year=2026,
+    development_status=DEPLOYMENT_STATUS_BETA,
+    has_migrations=False,
+    main_branch="main",
+    claim=(
+        "Race-safe state machines for Django models: a protected PhaseField and transitions as one conditional UPDATE"
+    ),
+    readme_content=ReadmeContent(uses_internationalisation=False),
+    dependencies=[
+        f"Django>={SUPPORTED_DJANGO_VERSIONS[0]}",
+    ],
+    supported_django_versions=SUPPORTED_DJANGO_VERSIONS,
+    supported_python_versions=SUPPORTED_PYTHON_VERSIONS,
+    optional_dependencies={
+        "dev": [
+            *DEV_DEPENDENCIES,
+        ],
+    },
+    ruff_ignore_list=[],
+)

django_phase-0.1.0/.ambient-package-update/templates/snippets/content.tpl

@@ -0,0 +1,46 @@
+## Features
+
+* Declare the allowed transitions once, as a table on the field
+* Assigning the phase directly raises; only `move()` changes it
+* `move()` writes phase and further fields in **one** conditional `UPDATE`, so of two concurrent transitions from the
+  same phase exactly one succeeds
+* Every `save()` is guarded against a stale phase, so it can't silently undo a concurrent transition
+* Migrations see a plain `CharField` and never import `phase`
+* System checks catch a missing mixin, a second phase field or one inherited from a concrete parent model
+* `PhaseGuardError` gives refused actions a stable `code` for machines and a `detail` for humans
+* Overrides no private Django method
+
+```python
+from django.db import models
+from django.utils import timezone
+
+from phase.fields import PhaseField
+from phase.mixins.phase_guard import PhaseGuardMixin
+from phase.transitions import move
+
+
+class Order(PhaseGuardMixin, models.Model):
+    class Status(models.TextChoices):
+        OPEN = "open"
+        PAID = "paid"
+        SHIPPED = "shipped"
+        CANCELLED = "cancelled"
+
+    status = PhaseField(
+        max_length=10,
+        choices=Status.choices,
+        default=Status.OPEN,
+        transitions={
+            Status.OPEN: (Status.PAID, Status.CANCELLED),
+            Status.PAID: (Status.SHIPPED,),
+        },
+    )
+    paid_at = models.DateTimeField(null=True, blank=True)
+
+
+order = Order.objects.create()
+move(obj=order, to=Order.Status.PAID, paid_at=timezone.now())
+
+order.status = Order.Status.OPEN  # raises ProtectedPhaseFieldError
+move(obj=order, to=Order.Status.OPEN)  # raises IllegalPhaseTransitionError
+```

django_phase-0.1.0/.ambient-package-update/templates/snippets/tagline.tpl

@@ -0,0 +1,2 @@
+Race-safe state machines for Django models: a protected `PhaseField`, transitions as one conditional `UPDATE`, and
+guards that tell humans and machines why an action was refused.

django_phase-0.1.0/.editorconfig

@@ -0,0 +1,17 @@
+# http://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{py,rst,ini}]
+indent_style = space
+indent_size = 4
+
+[*.yml]
+indent_style = space
+indent_size = 2

django_phase-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Report a problem to help us improve
+title: ''
+labels: bug
+assignees: ''
+---
+
+## Describe the bug
+
+A clear and concise description of what the bug is.
+
+## To reproduce
+
+Steps to reproduce the behavior:
+
+1. ...
+2. ...
+3. ...
+
+## Expected behavior
+
+A clear and concise description of what you expected to happen.
+
+## Environment
+
+- `django-phase` version:
+- Python version:
+- Django version:
+- Operating system:
+
+## Additional context
+
+Add any other context, tracebacks, or screenshots about the problem here.

django_phase-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/beyonder-deutschland/django-phase/security/advisories/new
+    about: Please report security issues privately via a security advisory, not as a public issue.

django_phase-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+## Is your feature request related to a problem?
+
+A clear and concise description of what the problem is. Ex. I'm always
+frustrated when [...]
+
+## Describe the solution you'd like
+
+A clear and concise description of what you want to happen.
+
+## Describe alternatives you've considered
+
+A clear and concise description of any alternative solutions or features you've
+considered.
+
+## Additional context
+
+Add any other context or screenshots about the feature request here.

django_phase-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## Description
+
+Please include a summary of the change and which issue is fixed (if any).
+
+Fixes #(issue)
+
+## Type of change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update
+
+## Checklist
+
+- [ ] My code follows the style guidelines of this project (linting passes)
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] I have updated the documentation where necessary
+- [ ] I have added an entry to `CHANGES.md`
+- [ ] I have bumped the version in `phase/__init__.py`

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

@@ -0,0 +1,11 @@
+name: Unit tests
+
+on:
+  push:
+    branches:
+    - main
+  pull_request:
+
+jobs:
+  ci:
+    uses: ./.github/workflows/quality-gate.yml

django_phase-0.1.0/.github/workflows/quality-gate.yml

@@ -0,0 +1,94 @@
+name: CI jobs
+
+on:
+  workflow_call:
+
+jobs:
+  linting:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python 3.15
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.15"
+
+      - name: Install required packages
+        run: pip install pre-commit
+
+      - name: Run pre-commit hooks
+        run: pre-commit run --all-files
+
+  tests:
+    name: Python ${{ matrix.python-version }}, django ${{ matrix.django-version }}
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14', '3.15', ]
+        django-version: ['52', '60', '61', ]
+
+        # Exclude Python/Django combinations that are not supported upstream.
+        exclude:
+          - python-version: '3.15'
+            django-version: 52
+          - python-version: '3.11'
+            django-version: 60
+          - python-version: '3.15'
+            django-version: 60
+          - python-version: '3.11'
+            django-version: 61
+
+    steps:
+      - uses: actions/checkout@v7
+      - name: setup python
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+        with:
+          cache-suffix: ${{ github.ref_type }}
+      - name: Install tox
+        run: uv pip install --system tox tox-uv
+      - name: Run Tests
+        env:
+          TOXENV: django${{ matrix.django-version }}
+        run: tox
+      - name: Upload coverage data
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-data-${{ matrix.python-version }}-${{ matrix.django-version }}
+          path: '${{ github.workspace }}/.coverage'
+          include-hidden-files: true
+          if-no-files-found: error
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-24.04
+    needs: tests
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.15'
+
+      - name: Install dependencies
+        run: python -m pip install --upgrade coverage[toml]
+
+      - name: Download data
+        uses: actions/download-artifact@v8
+        with:
+          path: ${{ github.workspace }}/coverage-reports
+          pattern: coverage-data-*
+          merge-multiple: false
+
+      - name: Combine coverage and fail if it's <100.0%
+        run: |
+          python -m coverage combine coverage-reports/*/.coverage
+          python -m coverage xml
+          python -m coverage html --skip-covered --skip-empty
+          python -m coverage report --fail-under=100.0
+          echo "## Coverage summary" >> $GITHUB_STEP_SUMMARY
+          python -m coverage report --format=markdown >> $GITHUB_STEP_SUMMARY

django_phase-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,136 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+# Restrictive default — each job declares only what it needs
+permissions:
+  contents: read
+
+jobs:
+  ci:
+    uses: ./.github/workflows/quality-gate.yml
+
+  check-branch:
+    name: Verify tag is on main
+    runs-on: ubuntu-24.04
+    outputs:
+      on-main: ${{ steps.check.outputs.on-main }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Check if tag is on main
+        id: check
+        run: |
+          git fetch origin main
+          if git merge-base --is-ancestor "${{ github.sha }}" origin/main; then
+            echo "on-main=true" >> $GITHUB_OUTPUT
+          else
+            echo "Tag is not on main, skipping release." >&2
+            echo "on-main=false" >> $GITHUB_OUTPUT
+          fi
+
+  build:
+    name: Build distribution packages
+    runs-on: ubuntu-24.04
+    needs: [ci, check-branch]
+    if: needs.check-branch.outputs.on-main == 'true'
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up Python 3.15
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.15"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+
+      - name: Build packages
+        run: uv build
+
+      - name: Upload distribution packages
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  sign:
+    name: Sign distribution packages
+    runs-on: ubuntu-24.04
+    needs: build
+    permissions:
+      id-token: write  # required for Sigstore OIDC signing
+      contents: read
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Sign packages with Sigstore
+        uses: sigstore/gh-action-sigstore-python@v3.5.0
+        with:
+          inputs: >-
+            ./dist/*.tar.gz
+            ./dist/*.whl
+
+      - name: Upload signed distribution packages
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist-signed
+          path: dist/
+          if-no-files-found: error
+
+  github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-24.04
+    needs: sign
+    permissions:
+      contents: write  # required to create GitHub releases
+    steps:
+      - name: Download signed distribution packages
+        uses: actions/download-artifact@v8
+        with:
+          name: dist-signed
+          path: dist/
+
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          shopt -s failglob
+          gh release create "${{ github.ref_name }}" \
+            --repo "${{ github.repository }}" \
+            --generate-notes \
+            dist/*
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-24.04
+    needs: sign
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI Trusted Publisher OIDC auth
+      contents: read
+    steps:
+      - name: Download signed distribution packages
+        uses: actions/download-artifact@v8
+        with:
+          name: dist-signed
+          path: dist/
+
+      - name: Remove Sigstore bundles (PyPI only accepts .whl and .tar.gz)
+        run: rm dist/*.sigstore.json
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Sigstore attestations are generated and uploaded to PyPI automatically
+        # when using Trusted Publishing — no extra configuration needed.

django_phase-0.1.0/.gitignore

@@ -0,0 +1,165 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# uv
+#   This is a library, so consumers never install from the lockfile. Not committing it avoids
+#   lockfile churn in every maintenance release.
+uv.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file. For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Deprecated dependency files
+requirements.txt
+
+# sphinx build folder
+_build
+
+# Compiled source #
+###################
+*.com
+*.class
+*.dll
+*.exe
+*.o
+
+# Test databases
+*.sqlite
+
+# AI
+.claude/

django_phase-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,60 @@
+# you find the full pre-commit-tools docu under:
+# https://pre-commit.com/
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.17.1
+    hooks:
+      # Run the Ruff formatter.
+      - id: ruff-format
+      # Run the Ruff linter.
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: 1.20.0
+    hooks:
+      - id: blacken-docs
+        args: [--line-length, "120"]
+        additional_dependencies:
+        - black==26.10.1
+        files: '(?:README\.md|\.ambient-package-update\/templates\/snippets\/.*\.tpl|docs\/.*\.(?:md|rst))'
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.22.0
+    hooks:
+      - id: pyupgrade
+        args: [ --py311-plus ]
+
+  - repo: https://github.com/adamchainz/django-upgrade
+    rev: 1.33.0
+    hooks:
+      - id: django-upgrade
+        args: [--target-version, "5.2"]
+
+  - repo: https://github.com/adamchainz/djade-pre-commit
+    rev: 1.10.0
+    hooks:
+    -   id: djade
+        args: [--target-version, "5.2"]
+        exclude: |
+          (?x)^(
+            charts/.*
+            |.*\.py
+          )$
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-ast
+      - id: check-builtin-literals
+      - id: check-case-conflict
+      - id: check-docstring-first
+      - id: check-executables-have-shebangs
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: fix-byte-order-marker
+      - id: mixed-line-ending
+      - id: trailing-whitespace

django_phase-0.1.0/.readthedocs.yaml

@@ -0,0 +1,33 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation.
+# Read the Docs supports uv natively, so we let it sync the project with the
+# "dev" extra (which contains the documentation dependencies).
+# See https://docs.readthedocs.com/platform/en/stable/config-file/v2.html#python-install
+python:
+  install:
+    - method: uv
+      command: sync
+      extras:
+        - dev