Metadata-Version: 2.5
Name: typed_classproperties
Version: 1.6.0
Summary: Typed decorators for classproperty and cached_classproperty.
Project-URL: Issues, https://github.com/CarrotManMatt/typed_classproperties/issues
Project-URL: Releases, https://github.com/CarrotManMatt/typed_classproperties/releases
Project-URL: Repository, https://github.com/CarrotManMatt/typed_classproperties
Author-email: Jonathan Clarke <jonathan.a.clarke@gmail.com>, Matt Norton <matt@carrotmanmatt.com>
Maintainer-email: Matt Norton <matt@carrotmanmatt.com>
License-Expression: MIT
License-File: LICENSE
Keywords: classmethod,decorator,property
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: 3.16
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: typing-extensions>=4.5.0; python_version < '3.12'
Description-Content-Type: text/markdown

# typed_classproperties

[![Pydowndoc](https://img.shields.io/badge/%F0%9F%A5%95-typed__classproperties-blue)](https://github.com/CarrotManMatt/typed_classproperties)
[![PyPI Version](https://img.shields.io/pypi/v/typed_classproperties)](https://pypi.org/project/typed_classproperties)
[![Python Version](https://img.shields.io/pypi/pyversions/typed_classproperties?logo=Python&logoColor=white&label=Python)](https://python.org/downloads)
[![Tests Status](https://github.com/CarrotManMatt/typed_classproperties/actions/workflows/check-build-publish.yaml/badge.svg)](https://github.com/CarrotManMatt/typed_classproperties/actions/workflows/check-build-publish.yaml)
[![mypy Status](https://img.shields.io/badge/mypy-checked-%232EBB4E&label=mypy)](https://mypy-lang.org)
[![pre-commit Status](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://pre-commit.com)
[![ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://ruff.rs)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://astral.sh/uv)

> Typed decorators for `classproperty` and `cached_classproperty`.
>
> **Python 3 compatible only**. **No dependencies**footnote:[The library `[typing_extensions](https://github.com/python/typing_extensions)` is required when running with a [Python](https://python.org) version less than `3.12`].

## Installation

This package is hosted on [PyPI](https://pypi.org) and can be installed using
[uv](https://astral.sh/uv) or [pip](https://pip.pypa.io).

**Add to your [uv project/script’s dependencies](https://docs.astral.sh/uv/concepts/projects#managing-dependencies)**
```bash
uv add typed_classproperties
```

**Install using [pip](https://pip.pypa.io) after [creating a virtual environment](https://docs.python.org/3/tutorial/venv)**
```bash
path/to/venv/python -m pip install typed_classproperties
```

## Example Usage

```python
from typing import override

from typed_classproperties import classproperty, cached_classproperty


class Foo:
    @override
    def __init__(self, bar: str) -> None:
        self.bar: str = bar

    @classproperty
    def BAR(cls) -> int:
        return 1


assert Foo.BAR == 1
assert Foo(bar="one").BAR == 1


class CachedFoo:
    @override
    def __init__(self, bar: str) -> None:
        self.bar: str = bar

    @cached_classproperty
    def BAR(cls) -> int:
        print("This will be executed only once")
        return 1


assert CachedFoo.BAR == 1
assert CachedFoo(bar="bar").FOO == 1
```

## Supported Type-Checkers

This package makes use of some reasonably advanced Python functionality that could be considered a hack.
The appropriate solution to correctly annotate the types matching the runtime behaviour of classproperties is explained in [PEP767](https://peps.python.org/pep-0767).
This PEP, however, is still in draft and not yet accepted; therefore, not all type checkers are supported.

While we will attempt to fix type annotation bugs in this project for alternative type-checkers, our focus is on the following officially supported type checkersfootnote:[The list of officially supported type checkers is subject to change between any minor version release]:

* [mypy](https://mypy-lang.org)
* [ty](https://astral.sh/ty) &le; 0.0.59footnote:[Support for [ty](https://astral.sh/ty) is capped to below [0.0.60](https://github.com/astral-sh/ty/releases/tag/0.0.60), which began to find type-errors with the hacks used in this project]

> **❗ IMPORTANT**\
Patches to fix bugs in this project for alternative type-checkers are welcome and much appreciated!

## Tests

See [tests.py](tests.py) for further usage examples and expected behaviour.

**To run tests**
```bash
uv run --group test -- pytest
```

## Credits

Credits to Denis Ryzhkov, on Stack Overflow, for the original implementation of the `@classproperty` decorator:
https://stackoverflow.com/a/13624858/1280629
