madman-bob/python-more-properties

A collection of property variants

more_properties

A collection of property variants.

Basic Usage

Variants behave mostly as the built-in property, except where noted.

Given the following class,

from more_properties import property, class_property, static_property


class Parrot:
    @property
    def name(self):
        return "Fred"

    @class_property
    def order(cls):
        return Psittaciformes

    @static_property
    def planet():
        return Earth

the properties may be accessed like so:

>>> Parrot().name
'Fred'
>>> Parrot.order
<class 'Psittaciformes'>
>>> Parrot.planet
<class 'Earth'>

Setters/Deleters

Setters and deleters are defined in the same way as the built-in property. Either with the decorator method

from more_properties import class_property


class Foo:
    name = "Foo"

    @class_property
    def identifier(cls):
        """Object identifier"""
        return cls.name.lower()

    @identifier.setter
    def identifier(cls, value):
        cls.name = value.title()

    @identifier.deleter
    def identifier(cls):
        cls.name = None

or the inline method

from more_properties import class_property


class Foo:
    name = "Foo"

    @classmethod
    def get_identifier(cls):
        return cls.name.lower()

    @classmethod
    def set_identifier(cls, value):
        cls.name = value.title()

    @classmethod
    def del_identifier(cls):
        cls.name = None

    identifier = class_property(
        get_identifier,
        set_identifier,
        del_identifier,
        "Object identifier"
    )

Reference

property

A modified version of the built-in property.

Always behaves as a data descriptor, regardless of which (if any) of getter, setter, and deleter are set.

Behaviour when accessed on a class, is undefined.

class_property

A property for classes. Both cls.x and instance.x call the getter with the class. Setting instance.x calls the setter with the class and value. Deleting instance.x call the deleter with the class only.

from more_properties import class_property


class Foo:
    @class_property
    def identifier(cls):
        """Class identifier"""
        return cls.__name__.lower()


class Bar(Foo):
    pass

>>> Foo.identifier
'foo'
>>> Foo().identifier
'foo'

>>> Bar.identifier
'bar'
>>> Bar().identifier
'bar'

classproperty provided as a synonym, for consistency with classmethod.

Due to the Python data model, using the setters/deleters on classes may not work as intended.

Getters always work as intended, and using setters/deleters on instances work as intended.

static_property

A property independent of its accessor. Both cls.x and instance.x call the getter with no parameters. Setting instance.x calls the setter with the value only. Deleting instance.x call the deleter with no parameters.

from more_properties import static_property


x = "bar"

class Foo:
    @static_property
    def val():
        return x

>>> Foo.val
'bar'
>>> Foo().val
'bar'

staticproperty provided as a synonym, for consistency with staticmethod.

Due to the Python data model, using the setters/deleters on classes may not work as intended.

Getters always work as intended, and using setters/deleters on instances work as intended.

cached_property

cached_class_property

cached_static_property

Variants of property, class_property, and static_property, respectively.

They are each used in the same way as the originals, but cache the value of the getters.

from dataclasses import dataclass

from more_properties import cached_property


@dataclass
class Foo:
    x: int

    @cached_property
    def y(self):
        print("Doing work")
        return self.x + 1

>>> bar = Foo(1)
>>> bar.y
Doing work
2
>>> bar.y
2

If the setters/deleters are defined, then the cache is cleared before they are called.

Further, the cache may be explicitly cleared through the clear_cache method, exposed only during class creation.

@dataclass
class Foo:
    x: int

    @cached_property
    def y(self):
        print("Doing work")
        return self.x + 1

    y_clear_cache = y.clear_cache

>>> bar = Foo(1)
>>> bar.y
Doing work
2
>>> bar.y
2
>>> bar.y_clear_cache()
>>> bar.y
Doing work
2

Installation

Install and update using the standard Python package manager pip:

pip install more_properties