kapro 0.0.1__tar.gz

kapro-0.0.1/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: kapro
+Version: 0.0.1
+Summary: kapro
+Author-email: Alex Kalaverin <alex@kalaver.in>
+Project-URL: Homepage, https://kalaver.in
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: kain>=1.1.11
+
+---
+title: kapro
+description: Class-level, mixed, and pinned descriptors for Python
+---
+
+[ref: #kapro]
+
+# kapro
+
+`kapro` is a small Python library of property descriptors.
+
+It gives you three public entry points:
+
+- `class_property` — a descriptor that lives on the class and is shared by every instance.
+- `mixed_property` — a descriptor that can be defined on the class but resolved per instance.
+- `pin` — a cached instance property that stores its value in the instance dictionary.
+
+[ref: #installation]
+
+## Installation
+
+Install with `uv`:
+
+```bash
+uv add kapro
+```
+
+Or with any PEP 517-compatible tool:
+
+```bash
+pip install kapro
+```
+
+[ref: #class-property]
+
+## Class-level properties with `class_property`
+
+`class_property` behaves like a class-level attribute, but it is computed lazily and cached on the class.
+
+```python
+from kapro import class_property
+
+class Config:
+    @class_property
+    def name(cls) -> str:
+        return "default"
+
+assert Config.name == "default"
+assert Config().name == "default"
+```
+
+The value is stored on the class, so every instance sees the same value.
+
+[ref: #mixed-property]
+
+## Mixed properties with `mixed_property`
+
+`mixed_property` calls the same function with the class when accessed on the class and with the instance when accessed on an instance.
+
+```python
+from kapro import mixed_property
+
+class User:
+    def __init__(self, id: int) -> None:
+        self.id = id
+
+    @mixed_property
+    def label(node) -> str:
+        if isinstance(node, type):
+            return "User model"
+        return f"user: {node.id}"
+
+assert User.label == "User model"
+assert User(id=7).label == "user: 7"
+```
+
+[ref: #pin]
+
+## Cached instance properties with `pin`
+
+`pin` is the cached equivalent of a plain method-based property.
+The first access computes the value and stores it in the instance dictionary.
+
+```python
+from kapro import pin
+
+class Expensive:
+    @pin
+    def payload(self) -> dict:
+        return {"loaded": True}
+
+obj = Expensive()
+assert obj.payload is obj.payload
+```
+
+[ref: #pin-flavors]
+
+### `pin` flavors
+
+`pin` exposes several variants through class attributes.
+
+| Flavor | Decorator | Caches on |
+| --- | --- | --- |
+| `native` | `@pin` | instance (default) |
+| `cls` | `@pin.cls` | class |
+| `any` | `@pin.any` | class or instance |
+| `pre` | `@pin.pre` | instance, runs before the underlying call |
+| `post` | `@pin.post` | instance, runs after the underlying call |
+
+```python
+from kapro import pin
+
+class Service:
+    @pin.cls
+    def version(cls) -> str:
+        return "1.0"
+
+assert Service.version == "1.0"
+assert Service().version == "1.0"
+```
+
+[ref: #full-example]
+
+## Full example
+
+```python
+from kapro import class_property, mixed_property, pin
+
+class App:
+    @class_property
+    def name(cls) -> str:
+        return "MyApp"
+
+    @mixed_property
+    def greeting(node) -> str:
+        return f"Hello from {node.name}"
+
+    @pin
+    def config(self) -> dict:
+        return {"debug": True}
+
+
+assert App.name == "MyApp"
+assert App.greeting == "Hello from MyApp"
+assert App().greeting == "Hello from MyApp"
+
+app = App()
+assert app.config == {"debug": True}
+assert app.config is app.config
+```

kapro-0.0.1/README.md

@@ -0,0 +1,150 @@
+---
+title: kapro
+description: Class-level, mixed, and pinned descriptors for Python
+---
+
+[ref: #kapro]
+
+# kapro
+
+`kapro` is a small Python library of property descriptors.
+
+It gives you three public entry points:
+
+- `class_property` — a descriptor that lives on the class and is shared by every instance.
+- `mixed_property` — a descriptor that can be defined on the class but resolved per instance.
+- `pin` — a cached instance property that stores its value in the instance dictionary.
+
+[ref: #installation]
+
+## Installation
+
+Install with `uv`:
+
+```bash
+uv add kapro
+```
+
+Or with any PEP 517-compatible tool:
+
+```bash
+pip install kapro
+```
+
+[ref: #class-property]
+
+## Class-level properties with `class_property`
+
+`class_property` behaves like a class-level attribute, but it is computed lazily and cached on the class.
+
+```python
+from kapro import class_property
+
+class Config:
+    @class_property
+    def name(cls) -> str:
+        return "default"
+
+assert Config.name == "default"
+assert Config().name == "default"
+```
+
+The value is stored on the class, so every instance sees the same value.
+
+[ref: #mixed-property]
+
+## Mixed properties with `mixed_property`
+
+`mixed_property` calls the same function with the class when accessed on the class and with the instance when accessed on an instance.
+
+```python
+from kapro import mixed_property
+
+class User:
+    def __init__(self, id: int) -> None:
+        self.id = id
+
+    @mixed_property
+    def label(node) -> str:
+        if isinstance(node, type):
+            return "User model"
+        return f"user: {node.id}"
+
+assert User.label == "User model"
+assert User(id=7).label == "user: 7"
+```
+
+[ref: #pin]
+
+## Cached instance properties with `pin`
+
+`pin` is the cached equivalent of a plain method-based property.
+The first access computes the value and stores it in the instance dictionary.
+
+```python
+from kapro import pin
+
+class Expensive:
+    @pin
+    def payload(self) -> dict:
+        return {"loaded": True}
+
+obj = Expensive()
+assert obj.payload is obj.payload
+```
+
+[ref: #pin-flavors]
+
+### `pin` flavors
+
+`pin` exposes several variants through class attributes.
+
+| Flavor | Decorator | Caches on |
+| --- | --- | --- |
+| `native` | `@pin` | instance (default) |
+| `cls` | `@pin.cls` | class |
+| `any` | `@pin.any` | class or instance |
+| `pre` | `@pin.pre` | instance, runs before the underlying call |
+| `post` | `@pin.post` | instance, runs after the underlying call |
+
+```python
+from kapro import pin
+
+class Service:
+    @pin.cls
+    def version(cls) -> str:
+        return "1.0"
+
+assert Service.version == "1.0"
+assert Service().version == "1.0"
+```
+
+[ref: #full-example]
+
+## Full example
+
+```python
+from kapro import class_property, mixed_property, pin
+
+class App:
+    @class_property
+    def name(cls) -> str:
+        return "MyApp"
+
+    @mixed_property
+    def greeting(node) -> str:
+        return f"Hello from {node.name}"
+
+    @pin
+    def config(self) -> dict:
+        return {"debug": True}
+
+
+assert App.name == "MyApp"
+assert App.greeting == "Hello from MyApp"
+assert App().greeting == "Hello from MyApp"
+
+app = App()
+assert app.config == {"debug": True}
+assert app.config is app.config
+```

kapro-0.0.1/pyproject.toml

@@ -0,0 +1,193 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [
+  "setuptools"
+]
+
+[dependency-groups]
+build = [
+  "setuptools"
+]
+dev = [
+  "async-asgi-testclient>=1.4.11",
+  "bandit[toml]>=1.9.4",
+  "basedmypy>=2.10.0",
+  "basedpyright>=1.39.4",
+  "better-exceptions>=0.3.3",
+  "black>=26.3.1",
+  "colorama>=0.4.6",
+  "faker>=40.18.0",
+  "hexora>=0.2.4",
+  "pre-commit>=4.6.0",
+  "pyrefly>=1.0.0",
+  "pytest-asyncio>=1.3.0",
+  "pytest-check>=2.8.0",
+  "pytest-clarity>=1.0.1",
+  "pytest-cov>=7.1.0",
+  "pytest-dotenv>=0.5.2",
+  "pytest-icdiff>=0.9",
+  "pytest-mock>=3.15.1",
+  "pytest-randomly>=4.1.0",
+  "pytest-timeout>=2.4.0",
+  "pytest-xdist>=3.8.0",
+  "pytest>=9.0.3",
+  "python-lsp-server[all]>=1.14.0",
+  "refurb>=2.3.1",
+  "righttyper>=0.1.0",
+  "ruff>=0.15.13",
+  "structlog>=25.5.0",
+  "time-machine>=3.2.0",
+  "ty>=0.0.36",
+  "typing-extensions>=4.15.0",
+  "typing-inspection>=0.4.2",
+  "uv-publish>=1.4",
+  "vulture>=2.16",
+  "yamlfix>=1.19.1",
+  "yamllint>=1.38.0"
+]
+
+[project]
+authors = [
+  {name = "Alex Kalaverin", email = "alex@kalaver.in"}
+]
+classifiers = [
+  "Intended Audience :: Developers",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "License :: OSI Approved :: BSD License",
+  "Operating System :: OS Independent"
+]
+dependencies = [
+  "kain>=1.1.11"
+]
+description = "kapro"
+name = "kapro"
+readme = "README.md"
+requires-python = ">=3.12,<3.14"
+version = "0.0.1"
+
+[project.urls]
+Homepage = "https://kalaver.in"
+
+[tool.bandit]
+exclude_dirs = [".venv", ".git"]
+
+[tool.black]
+line-length = 79
+target-version = ["py312"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "pragma: no cover",
+  "if __name__ == .__main__.:",
+  "^\\s+\\.{3}",
+  "if TYPE_CHECKING:",
+  "raise NotImplementedError",
+  "pass"
+]
+fail_under = 90
+show_missing = true
+
+[tool.coverage.run]
+branch = true
+omit = [
+  "*/migrations/*",
+  "*/__init__.py",
+  "*/if TYPE_CHECKING:*",
+  "tests/*"
+]
+source = ["src"]
+
+[tool.pylint.messages_control]
+enable = "all"
+
+[tool.pytest.ini_options]
+addopts = [
+  "-ra",
+  "--strict-config",
+  "--strict-markers",
+  "--tb=short",
+  "--timeout=60"
+]
+faulthandler_timeout = 60
+filterwarnings = [
+  "default"
+]
+markers = [
+]
+minversion = "8.0"
+testpaths = ["tests"]
+
+[tool.refurb]
+ignore = [
+  123,
+  149,
+  176,
+  191
+]
+
+[tool.ruff]
+exclude = []
+extend = "etc/lint/ruff.toml"
+
+[tool.ruff.lint.isort]
+section-order = [
+  "future",
+  "standard-library",
+  "third-party",
+  "first-party",
+  "local-project",
+  "local-folder"
+]
+
+[tool.ruff.lint.isort.sections]
+local-project = ["kapro"]
+
+[tool.ruff.lint.per-file-ignores]
+"*.pyi" = [
+  "ANN",
+  "N",
+  "PYI"
+]
+"contrib/*" = []
+"docs/*" = [
+  "INP001",  # File `docs/conf.py` is part of an implicit namespace package. Add an `__init__.py`.
+  "I001",  # [*] Import block is un-sorted or un-formatted
+  "PTH100",  # `os.path.abspath()` should be replaced by `Path.resolve()`
+  "A001"  # Variable `copyright` is shadowing a Python builtin
+]
+"src/*" = []
+"tests/*" = [
+  "ANN001",  # Missing type annotation for function argument `mock_workflow_is_replaying`
+  "ANN401",  # Dynamically typed expressions (typing.Any) are disallowed in `key`
+  "ARG001",  # Unused function argument: `node`
+  "ARG002",  # Unused method argument: `mock_workflow_info`
+  "ARG005",  # Unused lambda argument: `cls`
+  "B018",  # Found useless expression. Either assign it to a variable or remove it.
+  "FBT003",  # Boolean positional value in function call
+  "INP001",  # File `tests/workflows/test_turnover_workflows.py` is part of an implicit namespace package. Add an `__init__.py`.
+  "N805",  # First argument of a method should be named `self`
+  "N805",  # First argument of a method should be named `self`
+  "PLC0415",  # `import` should be at the top-level of a file
+  "PLR0124",  # Name compared with itself, consider replacing `Nothing == Nothing`
+  "PLR2004",  # Magic value used in comparison, consider replacing `3` with a constant variable
+  "PYI024",  # Use `typing.NamedTuple` instead of `collections.namedtuple`
+  "S101",  # Use of `assert` detected
+  "SLF001",  # Private member accessed: `_proxy`
+  "TC002",  # Move third-party import `faker.Faker` into a type-checking block
+  "TC003",  # Move standard library import `collections.abc.Generator` into a type-checking block
+  "TRY301"  # Abstract `raise` to an inner function
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ty.rules]
+possibly-missing-attribute = "ignore"
+
+[tool.uv]
+default-groups = [
+  "dev"
+]

kapro-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kapro-0.0.1/src/kapro/__init__.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import Any, TypeVar, final, overload, override
+
+from kapro.cached import (
+    cached_property,
+    class_cached_property,
+    mixed_cached_property,
+    post_cached_property,
+    pre_cached_property,
+)
+from kapro.class_property import class_property, mixed_property
+from kapro.primitives import (
+    ContextFaultError,
+    Nothing,
+    bound_property,
+)
+
+T_co = TypeVar("T_co", covariant=True)
+
+
+@final
+class pin[T_co](bound_property[T_co]):  # noqa: N801
+    native = cached_property
+    cls = class_cached_property
+    any = mixed_cached_property
+    pre = pre_cached_property
+    post = post_cached_property
+
+    @overload
+    def __get__(
+        self,
+        node: None,
+        klass: Any = ...,  # noqa: ANN401
+    ) -> pin[T_co]: ...
+
+    @overload
+    def __get__(
+        self,
+        node: object,
+        klass: Any = ...,  # noqa: ANN401
+    ) -> T_co: ...
+
+    @override
+    def __get__(
+        self,
+        node: object | None,
+        klass: Any = Nothing,
+    ) -> pin[T_co] | T_co:
+        if node is None:
+            raise ContextFaultError(self.header_with_context(klass))
+
+        cache = getattr(node, "__dict__", None)
+        if cache is None:
+            raise TypeError(
+                f"{self.header_with_context(node)} has no __dict__",
+            )
+
+        try:
+            return cache[self.name]  # type: ignore[no-any-return, index]
+
+        except KeyError:
+            value = self.function(node)
+            cache[self.name] = value  # type: ignore[index]
+            return value  # type: ignore[no-any-return]
+
+
+__all__ = (
+    "class_property",
+    "mixed_property",
+    "pin",
+)

kapro-0.0.1/src/kapro/cached/__init__.py

@@ -0,0 +1,29 @@
+from kapro.cached.instance import cached_property
+from kapro.cached.klass import (
+    class_cached_property,
+    class_parent_cached_property,
+)
+from kapro.cached.mixed import (
+    mixed_cached_property,
+    mixed_parent_cached_property,
+)
+from kapro.cached.post import (
+    post_cached_property,
+    post_parent_cached_property,
+)
+from kapro.cached.pre import (
+    pre_cached_property,
+    pre_parent_cached_property,
+)
+
+__all__ = (
+    "cached_property",
+    "class_cached_property",
+    "class_parent_cached_property",
+    "mixed_cached_property",
+    "mixed_parent_cached_property",
+    "post_cached_property",
+    "post_parent_cached_property",
+    "pre_cached_property",
+    "pre_parent_cached_property",
+)