contextmodel 0.1.0__tar.gz

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

@@ -0,0 +1,128 @@
+name: ci
+
+on:
+  push:
+    branches: ['main', 'test-me-*']
+    tags: ['v*']
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  UV_LOCKED: 1
+  UV_NO_SYNC: 1
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  check:
+    if: ${{ !cancelled() }}
+    name: ${{ matrix.version }} ${{matrix.platform}}
+    runs-on: ${{ matrix.platform }}
+
+    env:
+      FORCE_COLOR: 1
+      PY_COLORS: 1
+      UV_PYTHON: ${{ matrix.version }}
+
+    strategy:
+      fail-fast: false
+      # https://blog.jaraco.com/efficient-use-of-ci-resources/
+      matrix:
+        version: ['3.12', '3.14']
+        platform: [ubuntu-latest, windows-latest]
+        include:
+        - version: '3.13'
+          platform: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        submodules: true
+
+    - uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+
+    - name: Install
+      id: install
+      run: uv sync
+
+    - name: Run unit tests
+      run: uv run pytest -vv
+      if: ${{ !cancelled() && steps.install.conclusion == 'success' }}
+
+    - name: Check formatting
+      id: formatting
+      run: uv run ruff format . --diff
+      if: ${{ !cancelled() && steps.install.conclusion == 'success' }}
+
+    - name: Lint
+      id: linting
+      run: uv run ruff check --output-format github
+      if: ${{ !cancelled() && steps.install.conclusion == 'success' }}
+
+    - name: Check type safety
+      id: types
+      run: uv run ty check .
+      if: ${{ !cancelled() && steps.install.conclusion == 'success' }}
+
+  release:
+    needs: [check]
+
+    if: ${{ github.ref_type == 'tag' }}
+
+    name: pypi release
+    runs-on: ubuntu-latest
+    environment: release
+
+    permissions:
+      id-token: write
+      contents: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: true
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+
+      - name: Validate tag
+        id: validate-tag
+        run: |
+          set -CETeuxo pipefail
+
+          project_version=v$(uvx --with hatch-vcs hatchling version)
+          tag=${GITHUB_REF#refs/tags/}
+
+          [[ "$tag" == "$project_version" ]] || {
+            echo "Tag $tag does not match project version $project_version."
+            echo "Did you properly bump the version / set up dynamic versioning?"
+            exit 1
+          }
+
+      - name: Build package distributions
+        id: build
+        run: uv build --out-dir dist
+
+      - name: Publish package distributions
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: 'Create a GitHub release'
+        uses: ncipollo/release-action@v1.18.0
+        with:
+          prerelease: false
+          draft: false
+          makeLatest: true
+          tag: "${{ github.ref_name }}"
+          name: "${{ github.ref_name }}"
+          generateReleaseNotes: true

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

@@ -0,0 +1,21 @@
+# See https://pre-commit.com for more information
+default_install_hook_types: [pre-commit, pre-push]
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-yaml
+    -   id: debug-statements
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.5
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.9.26
+    hooks:
+      - id: uv-lock
+        stages: [pre-push]

contextmodel-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

contextmodel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bartosz Sławecki
+
+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.

contextmodel-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: contextmodel
+Version: 0.1.0
+Summary: A nice interface to context variables
+License-File: LICENSE
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# contextmodel
+Alternative interface to context variables for practical scenarios.
+
+```pycon
+>>> from contextmodel import ContextModel, context_create, context_get
+>>> from dataclasses import dataclass
+
+>>> @dataclass
+... class Foo(ContextModel):
+...     x: int | None = None
+
+>>> @context_create(Foo, x=1)
+... def f() -> None:
+...     print(context_get(Foo))
+>>> f()
+Foo(x=1)
+
+>>> with Foo.model_context.create(x=2):
+...     print(Foo.model_current.x)
+2
+
+>>> @Foo.model_context.create(x=3)
+... def f() -> None:
+...     print(Foo.model_current.x)
+>>> f()
+3
+
+
+```
+
+Works with type hints:
+
+<img width="821" height="454" alt="image" src="https://github.com/user-attachments/assets/6c4f5b4b-48b5-4807-a6aa-bf9cd6b8e3e4" />

contextmodel-0.1.0/README.md

@@ -0,0 +1,33 @@
+# contextmodel
+Alternative interface to context variables for practical scenarios.
+
+```pycon
+>>> from contextmodel import ContextModel, context_create, context_get
+>>> from dataclasses import dataclass
+
+>>> @dataclass
+... class Foo(ContextModel):
+...     x: int | None = None
+
+>>> @context_create(Foo, x=1)
+... def f() -> None:
+...     print(context_get(Foo))
+>>> f()
+Foo(x=1)
+
+>>> with Foo.model_context.create(x=2):
+...     print(Foo.model_current.x)
+2
+
+>>> @Foo.model_context.create(x=3)
+... def f() -> None:
+...     print(Foo.model_current.x)
+>>> f()
+3
+
+
+```
+
+Works with type hints:
+
+<img width="821" height="454" alt="image" src="https://github.com/user-attachments/assets/6c4f5b4b-48b5-4807-a6aa-bf9cd6b8e3e4" />

contextmodel-0.1.0/contextmodel/__init__.py

@@ -0,0 +1,147 @@
+from collections.abc import Callable, Generator
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from functools import cache, partial
+from typing import ClassVar
+
+
+class Context[M: ContextModel, **P]:
+    """
+    Context. Call it to create a new object.
+
+    >>> from dataclasses import dataclass
+
+    >>> @dataclass
+    ... class Foo(ContextModel):
+    ...     x: int | None = None
+
+    >>> @context_create(Foo, x=1)
+    ... def f() -> None:
+    ...     print(context_get(Foo))
+    >>> f()
+    Foo(x=1)
+
+    >>> with Foo.model_context.create(x=2):
+    ...     print(Foo.model_current.x)
+    2
+
+    >>> @Foo.model_context.create(x=3)
+    ... def f() -> None:
+    ...     print(Foo.model_current.x)
+    >>> f()
+    3
+
+    """
+
+    def __init__(self, model_class: Callable[P, M], variable: ContextVar[M]) -> None:
+        self.model_class = model_class
+        self.variable = variable
+
+    def get(self) -> M:
+        return self.variable.get()
+
+    def set(self, model: M) -> Generator[Token[M]]:
+        token = self.variable.set(model)
+        try:
+            yield token
+        finally:
+            token.var.reset(token)
+
+    @contextmanager
+    def create(self, *args: P.args, **kwargs: P.kwargs) -> Generator[Token[M]]:
+        return self.set(self.model_class(*args, **kwargs))
+
+
+def context_get[M: ContextModel](model_class: type[M]) -> M:
+    """
+    Get the current context model instance.
+
+    >>> from dataclasses import dataclass, field
+
+    >>> @dataclass
+    ... class Foo(ContextModel):
+    ...     x: int = 1
+
+    >>> with Foo.model_context.create(x=2):
+    ...     print(context_get(Foo))
+    Foo(x=2)
+    """
+    return context_of(model_class).get()
+
+
+def future_context_get[M: ContextModel](model_class: type[M]) -> Callable[[], M]:
+    """
+    Return a callback to return a value from context. Useful as "factories".
+
+    >>> from dataclasses import dataclass, field
+
+    >>> @dataclass
+    ... class Foo(ContextModel):
+    ...     x: int = 1
+
+    >>> @dataclass
+    ... class MyData:
+    ...     foo: Foo = field(default_factory=future_context_get(Foo))
+
+    >>> MyData(foo=Foo())
+    MyData(foo=Foo(x=1))
+
+    >>> with Foo.model_context.create(x=2):
+    ...     print(MyData())
+    MyData(foo=Foo(x=2))
+
+    """
+    return partial(context_get, model_class)
+
+
+@cache
+def context_of[M: ContextModel, **P](
+    model_class: Callable[P, M],
+) -> Context[M, P]:
+    auto_name = getattr(model_class, "__name__", format(model_class))
+    return Context(model_class=model_class, variable=ContextVar[M](auto_name))
+
+
+@contextmanager
+def context_create[**P, M: Context](
+    model_class: Callable[P, M],
+    /,
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> Generator[M]:
+    context = context_of(model_class)
+    return context.set(context.model_class(*args, **kwargs))
+
+
+@contextmanager
+def context_set[**P, M: Context](
+    model_class: Callable[P, M],
+    /,
+    *args: P.args,
+    **kwargs: P.kwargs,
+) -> Generator[M]:
+    context = context_of(model_class)
+    return context.set(context.model_class(*args, **kwargs))
+
+
+class _ContextGetter:
+    def __get__[M: ContextModel, **P](
+        self,
+        instance: M | None,
+        owner: Callable[P, M],
+    ) -> Context[M, P]:
+        return context_of(owner or type(instance))
+
+
+class _ModelGetter:
+    def __get__[M: ContextModel, **P](
+        self,
+        instance: M | None,
+        owner: Callable[P, M],
+    ) -> M:
+        return context_get(owner if instance is None else instance)  # type: ignore[invalid-argument-type]
+
+
+class ContextModel:
+    model_context: ClassVar[_ContextGetter] = _ContextGetter()
+    model_current: ClassVar[_ModelGetter] = _ModelGetter()

contextmodel-0.1.0/pyproject.toml

@@ -0,0 +1,121 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "contextmodel"
+dynamic = ["version"]
+description = "A nice interface to context variables"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = []
+
+[dependency-groups]
+dev = ["pre-commit>=4.2.0", "ruff>=0.11.8", "ty>=0.0.13"]
+test = [
+    "detect-test-pollution>=1.2.0",
+    "hypothesis>=6.131.0",
+    "inline-snapshot>=0.20.8",
+    "pytest>=8.3.4",
+    "pytest-accept>=0.1.12",
+    "pytest-mock>=3.14.0",
+    "pytest-subtests>=0.14.1",
+    "pytest-sugar>=1.0.0",
+]
+types = []
+docs = [
+    "markdown-exec>=1.10.3",
+    "mike>=2.1.3",
+    "mkdocs>=1.6.1",
+    "mkdocs-git-revision-date-localized-plugin>=1.4.5",
+    "mkdocs-macros-plugin>=1.3.7",
+    "mkdocs-material>=9.6.13",
+    "mkdocstrings>=0.29.1",
+    "mkdocstrings-python>=1.16.10",
+]
+
+[tool.uv]
+required-version = "~=0.9"
+default-groups = ["dev", "test", "types", "docs"]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.pytest.ini_options]
+pythonpath = "."
+addopts = ["--import-mode=importlib", "--doctest-modules", "--doctest-glob=**.md"]
+
+[tool.ruff.lint]
+exclude = ["**samples/**"]
+select = ["ALL"]
+ignore = [
+    # Description: Dynamically typed expressions (typing.Any) are disallowed
+    # Rationale:
+    #  We use Any to allow user to constrain return types of our functions on their own.
+    #  For example, having a function `def foo() -> Any: ...` allows user to write
+    #  `my_foo: int = foo()` and have it passed type checking, since `Any` as a gradual
+    #  form is assignable to any type
+    "ANN401",
+
+    # Description: 1 blank line required before class docstring
+    # Rationale: Remove the warning -- D211 (no-blank-line-before-class) preferred
+    "D203",
+
+    # Description: Multi-line docstring summary should start at the second line
+    # Rationale: Remove the warning -- D213 (multi-line-summary-second-line) preferred
+    "D212",
+
+    # Description: Line contains TODO, consider resolving the issue
+    # Rationale: Not appropriate for the project
+    "FIX002",
+
+    # Description: Implicitly concatenated string literals on one line
+    # Rationale: Conflicts with the formatter
+    "ISC001",
+
+    # Description: Function is too complex
+    # Rationale: Marginal importance
+    "C901",
+
+    # Description: Trailing comma missing
+    # Rationale: Conflicts with the formatter
+    "COM812",
+
+    # Description: File is part of an implicit namespace package. Add an `__init__.py`
+    # Rationale: Implicit namespace packages are a feature
+    "INP001",
+
+    # Description: Missing documentation
+    # Rationale: Important, but secondary concern
+    "D100", # Public module
+    "D101", # Public class
+    "D102", # Public method
+    "D103", # Public function
+    "D104", # Public package
+    "D105", # Magic method
+    "D107", # __init__
+
+    # Description: Use of `assert` detected
+    # Rationale: Assertions aren't bad and can be disabled with `python -O`
+    "S101",
+
+    # Description: Missing issue link on the line following this TODO
+    # Rationale: Own semantics
+    "TD003",
+
+    # Description: Wildcard imports used
+    # Rationale: Waiting for red knot to understand them
+    "F403",
+
+    # Description: Move third-party import into a type-checking block
+    # Rationale: Start-up time is not yet that important
+    "TC",
+
+    # Description: Private member accessed
+    # Rationale: In reality, this check causes more trouble than prevents bad things
+    "SLF001",
+
+    # Description: Pathlib lints
+    # Rationale: Pathlib is intentionally not used
+    "PTH",
+]