classicist 1.0.0__tar.gz

classicist-1.0.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2025 Daniel Sissman.
+
+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.

classicist-1.0.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: classicist
+Version: 1.0.0
+Summary: Classy class decorators for Python.
+Author: Daniel Sissman
+License-Expression: MIT
+Project-URL: documentation, https://github.com/bluebinary/classicist/blob/main/README.md
+Project-URL: changelog, https://github.com/bluebinary/classicist/blob/main/CHANGELOG.md
+Project-URL: repository, https://github.com/bluebinary/classicist
+Project-URL: issues, https://github.com/bluebinary/classicist/issues
+Project-URL: homepage, https://github.com/bluebinary/classicist
+Keywords: decorator,hybrid method,class method,instance method,class property,class properties
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Provides-Extra: development
+Requires-Dist: black==24.10.*; extra == "development"
+Requires-Dist: pytest==8.3.*; extra == "development"
+Requires-Dist: pytest-codeblocks==0.17.0; extra == "development"
+Provides-Extra: distribution
+Requires-Dist: build; extra == "distribution"
+Requires-Dist: twine; extra == "distribution"
+Requires-Dist: wheel; extra == "distribution"
+Dynamic: license-file
+
+# Classicist: Classy Class Decorators & Extensions
+
+The Classicist library provides several useful class decorators for Python class methods
+including a `hybridmethod` decorator that allows methods defined in a class to be used
+both a class method and an instance method, and a `classproperty` decorator that allows
+class methods to be accessed as class properties.
+
+The `classicist` library was previously named `hybridmethod` so if a prior version had been
+installed, please update references to the new library name. Installation of the
+library via its old name, `hybridmethod`, will install the new `classicist` library with
+a mapping for backwards compatibility so that code continues to function as before.
+
+### Requirements
+
+The Classicist library has been tested with Python 3.9, 3.10, 3.11, 3.12 and 3.13. The library is not compatible with Python 3.8 or earlier.
+
+### Installation
+
+The Classicist library is available from PyPI, so may be added to a project's dependencies via its `requirements.txt` file or similar by referencing the Classicist library's name, `classicist`, or the library may be installed directly into your local runtime environment using `pip` via the `pip install` command by entering the following into your shell:
+
+	$ pip install classicist
+
+#### Hybrid Methods
+
+The Classicist library provides a `hybridmethod` method decorator that allows methods
+defined in a class to be used as both a class method and an instance method.
+
+The `@hybridmethod` decorator provided by the library wraps methods defined in classes
+using the usual `@decorator` syntax. Methods defined in classes that are decorated with
+the `@hybridmethod` decorator can then be accessed as both class methods and as instance
+methods, with the first argument passed to the method being a reference to either the
+class when the method is called as a class method or to the instance when the method is
+called as an instance method.
+
+If a class-level property is defined and then an instance-level property is created with
+the same name that shadows the class-level property, the hybrid method can be used to
+interact with both the class-level property and the instance-level property simply based
+on whether the hybrid method was called directly on the class or on an a class instance.
+
+If desired, a simple check of the value of the first variable passed to a hybrid method
+using `isinstance(<variable>, <class>)` allows one to determine if the call was made on
+an instance of the class in which case `isinstance()` evaluates to `True` or if the call
+was made on the class itself, in which case `isinstance()` evaluates to `False`.
+
+The variable passed as the first argument to the method may have any name, including as
+is common in Python, `self`, although the use of `self` as the name of this argument on
+an instance method is just customary and the name has no significance.
+
+If using the `isinstance(<variable>, <class>)` check as described above is used simply
+substitute in the name of the first variable of a hybrid method for `<variable>` and the
+name of the class for `<class>`.
+
+#### Hybrid Methods: Usage
+
+To use the `hybridmethod` decorator import the decorator from the `classicist` library
+and use it to decorate the class methods you wish to use as both class methods and
+instance methods:
+
+```python
+from classicist import hybridmethod
+
+class hybridcollection(object):
+    items: list[str] = []
+
+    def __init__(self):
+        # Create an 'items' instance variable; note that this shadows the class variable
+        # of the same name which can still be accessed directly via self.__class__.items
+        self.items: list[object] = []
+
+    @hybridmethod
+    def add_item(self, item: object):
+        # We can use the following line to differentiate between the call being made on
+        # an instance or directly on the class; isinstance(self, <class>) returns True
+        # if the method was called on an instance of the class, or False if the method
+        # was called on the class directly; the 'self' variable will reference either
+        # the instance or the class; although 'self' is traditionally used in Python as
+        # reference to the instance
+        if isinstance(self, hybridcollection):
+            self.items.append(item)
+        else:
+            self.items.append(item)
+
+    def get_class_items(self) -> list[object]:
+        return self.__class__.items
+
+    def get_instance_items(self) -> list[object]:
+        return self.items
+
+    def get_combined_items(self) -> list[object]:
+        return self.__class__.items + self.items
+
+hybridcollection.add_item("ABC")  # Add an item to the class-level items list
+
+collection = hybridcollection()
+
+collection.add_item("XYZ")  # Add an item to the instance-level items list
+
+assert collection.get_class_items() == ["ABC"]
+
+assert collection.get_instance_items() == ["XYZ"]
+
+assert collection.get_combined_items() == ["ABC", "XYZ"]
+```
+
+#### Class Properties
+
+The Classicist library provides a `classproperty` method decorator that allows class
+methods to be accessed as class properties.
+
+The `@classproperty` decorator provided by the library wraps methods defined in classes
+using the usual `@decorator` syntax. Methods defined in classes that are decorated with
+the `@classproperty` decorator can then be accessed as though they were real properties
+on the class.
+
+The `@classproperty` decorator addresses the removal in Python 3.13 of the prior support
+for combining the `@classmethod` and `@property` decorators to create class properties,
+a change which was made due to complexity in the underlying interpreter implementation.
+
+#### Class Properties: Usage
+
+To use the `classproperty` decorator import the decorator from the `classicist` library
+and use it to decorate any class methods you wish to access as class properties.
+
+```python
+from classicist import classproperty
+
+class exampleclass(object):
+    @classproperty
+    def greeting(cls) -> str:
+        """The 'greeting' class method has been decorated with classproperty so acts as
+        a property; here we could do some work to generate a return value."""
+        return "hello"
+
+assert isinstance(exampleclass, type)
+assert issubclass(exampleclass, exampleclass)
+assert issubclass(exampleclass, object)
+
+# We can access `.greeting` as though it was defined as a property:
+# The return value of `.greeting` is indiscernible from the value being returned
+assert isinstance(exampleclass.greeting, str)
+assert exampleclass.greeting == "hello"
+```
+
+⚠️ An important caveat regarding class properties which applies equally to the method of
+supporting class properties provided by this library, and to class properties which are
+supported natively in Python 3.9 – 3.12 by combining the `@classmethod` and `@property`
+decorators, is that unfortunately unless a custom metaclass is used to intervene, class
+properties can be overwritten by value assignment.
+
+This is a result of differences in Python's handling for descriptors between classes and
+instances of classes. For both classes and instances, the `__get__` descriptor is called
+while the `__set__` and `__delete__` descriptor methods will only be called on instances
+such that we have no way to be involved in the property reassignment or deletion process
+as would be the case for properties on instances where we can create our own setter and
+deleter methods in addition to the getter.
+
+This caveat can be remedied through a custom metaclass however, which overrides default
+behaviour, and is able to intercept the `__setattr_` and `__delattr__` calls as needed.
+
+```python
+from classicist import classproperty
+
+class exampleclass(object):
+    @classproperty
+    def greeting(cls) -> str:
+        # Generate a return value here
+        return "hello"
+
+# We can access `.greeting` as though it was defined as a property:
+assert exampleclass.greeting == "hello"
+
+# Note: The `.greeting` property will be reassigned to the new value, "goodbye":
+exampleclass.greeting = "goodbye"
+assert exampleclass.greeting == "goodbye"
+```
+
+As can be seen with the method of natively supporting class properties, they could also
+have their values reassigned without warning:
+
+```python
+import sys
+import pytest
+
+# As Python only natively supported combining @classmethod and @property between version
+# 3.9 and 3.12, the example below is not usable on other versions, such as 3.13+
+if sys.version_info.major == 3 and not (9 <= sys.version_info.minor <= 12):
+    pytest.skip("This test can run on Python versions 3.9 – 3.12")
+
+class exampleclass(object):
+    @classmethod
+    @property
+    def greeting(cls) -> str:
+        # Generate a return value here
+        return "hello"
+
+# We can access `.greeting` as though it was defined as a property:
+assert exampleclass.greeting == "hello"
+
+# Note: The `.greeting` property will be reassigned to the new value, "goodbye":
+exampleclass.greeting = "goodbye"
+assert exampleclass.greeting == "goodbye"
+```
+
+### Unit Tests
+
+The Classicist library includes a suite of comprehensive unit tests which ensure that
+the library functionality operates as expected. The unit tests were developed with and
+are run via `pytest`.
+
+To ensure that the unit tests are run within a predictable runtime environment where all of the necessary dependencies are available, a [Docker](https://www.docker.com) image is created within which the tests are run. To run the unit tests, ensure Docker and Docker Compose is [installed](https://docs.docker.com/engine/install/), and perform the following commands, which will build the Docker image via `docker compose build` and then run the tests via `docker compose run` – the output of running the tests will be displayed:
+
+```shell
+$ docker compose build
+$ docker compose run tests
+```
+
+To run the unit tests with optional command line arguments being passed to `pytest`, append the relevant arguments to the `docker compose run tests` command, as follows, for example passing `-vv` to enable verbose output:
+
+```shell
+$ docker compose run tests -vv
+```
+
+See the documentation for [PyTest](https://docs.pytest.org/en/latest/) regarding available optional command line arguments.
+
+### Copyright & License Information
+
+Copyright © 2025 Daniel Sissman; licensed under the MIT License.

classicist-1.0.0/README.md

@@ -0,0 +1,227 @@
+# Classicist: Classy Class Decorators & Extensions
+
+The Classicist library provides several useful class decorators for Python class methods
+including a `hybridmethod` decorator that allows methods defined in a class to be used
+both a class method and an instance method, and a `classproperty` decorator that allows
+class methods to be accessed as class properties.
+
+The `classicist` library was previously named `hybridmethod` so if a prior version had been
+installed, please update references to the new library name. Installation of the
+library via its old name, `hybridmethod`, will install the new `classicist` library with
+a mapping for backwards compatibility so that code continues to function as before.
+
+### Requirements
+
+The Classicist library has been tested with Python 3.9, 3.10, 3.11, 3.12 and 3.13. The library is not compatible with Python 3.8 or earlier.
+
+### Installation
+
+The Classicist library is available from PyPI, so may be added to a project's dependencies via its `requirements.txt` file or similar by referencing the Classicist library's name, `classicist`, or the library may be installed directly into your local runtime environment using `pip` via the `pip install` command by entering the following into your shell:
+
+	$ pip install classicist
+
+#### Hybrid Methods
+
+The Classicist library provides a `hybridmethod` method decorator that allows methods
+defined in a class to be used as both a class method and an instance method.
+
+The `@hybridmethod` decorator provided by the library wraps methods defined in classes
+using the usual `@decorator` syntax. Methods defined in classes that are decorated with
+the `@hybridmethod` decorator can then be accessed as both class methods and as instance
+methods, with the first argument passed to the method being a reference to either the
+class when the method is called as a class method or to the instance when the method is
+called as an instance method.
+
+If a class-level property is defined and then an instance-level property is created with
+the same name that shadows the class-level property, the hybrid method can be used to
+interact with both the class-level property and the instance-level property simply based
+on whether the hybrid method was called directly on the class or on an a class instance.
+
+If desired, a simple check of the value of the first variable passed to a hybrid method
+using `isinstance(<variable>, <class>)` allows one to determine if the call was made on
+an instance of the class in which case `isinstance()` evaluates to `True` or if the call
+was made on the class itself, in which case `isinstance()` evaluates to `False`.
+
+The variable passed as the first argument to the method may have any name, including as
+is common in Python, `self`, although the use of `self` as the name of this argument on
+an instance method is just customary and the name has no significance.
+
+If using the `isinstance(<variable>, <class>)` check as described above is used simply
+substitute in the name of the first variable of a hybrid method for `<variable>` and the
+name of the class for `<class>`.
+
+#### Hybrid Methods: Usage
+
+To use the `hybridmethod` decorator import the decorator from the `classicist` library
+and use it to decorate the class methods you wish to use as both class methods and
+instance methods:
+
+```python
+from classicist import hybridmethod
+
+class hybridcollection(object):
+    items: list[str] = []
+
+    def __init__(self):
+        # Create an 'items' instance variable; note that this shadows the class variable
+        # of the same name which can still be accessed directly via self.__class__.items
+        self.items: list[object] = []
+
+    @hybridmethod
+    def add_item(self, item: object):
+        # We can use the following line to differentiate between the call being made on
+        # an instance or directly on the class; isinstance(self, <class>) returns True
+        # if the method was called on an instance of the class, or False if the method
+        # was called on the class directly; the 'self' variable will reference either
+        # the instance or the class; although 'self' is traditionally used in Python as
+        # reference to the instance
+        if isinstance(self, hybridcollection):
+            self.items.append(item)
+        else:
+            self.items.append(item)
+
+    def get_class_items(self) -> list[object]:
+        return self.__class__.items
+
+    def get_instance_items(self) -> list[object]:
+        return self.items
+
+    def get_combined_items(self) -> list[object]:
+        return self.__class__.items + self.items
+
+hybridcollection.add_item("ABC")  # Add an item to the class-level items list
+
+collection = hybridcollection()
+
+collection.add_item("XYZ")  # Add an item to the instance-level items list
+
+assert collection.get_class_items() == ["ABC"]
+
+assert collection.get_instance_items() == ["XYZ"]
+
+assert collection.get_combined_items() == ["ABC", "XYZ"]
+```
+
+#### Class Properties
+
+The Classicist library provides a `classproperty` method decorator that allows class
+methods to be accessed as class properties.
+
+The `@classproperty` decorator provided by the library wraps methods defined in classes
+using the usual `@decorator` syntax. Methods defined in classes that are decorated with
+the `@classproperty` decorator can then be accessed as though they were real properties
+on the class.
+
+The `@classproperty` decorator addresses the removal in Python 3.13 of the prior support
+for combining the `@classmethod` and `@property` decorators to create class properties,
+a change which was made due to complexity in the underlying interpreter implementation.
+
+#### Class Properties: Usage
+
+To use the `classproperty` decorator import the decorator from the `classicist` library
+and use it to decorate any class methods you wish to access as class properties.
+
+```python
+from classicist import classproperty
+
+class exampleclass(object):
+    @classproperty
+    def greeting(cls) -> str:
+        """The 'greeting' class method has been decorated with classproperty so acts as
+        a property; here we could do some work to generate a return value."""
+        return "hello"
+
+assert isinstance(exampleclass, type)
+assert issubclass(exampleclass, exampleclass)
+assert issubclass(exampleclass, object)
+
+# We can access `.greeting` as though it was defined as a property:
+# The return value of `.greeting` is indiscernible from the value being returned
+assert isinstance(exampleclass.greeting, str)
+assert exampleclass.greeting == "hello"
+```
+
+⚠️ An important caveat regarding class properties which applies equally to the method of
+supporting class properties provided by this library, and to class properties which are
+supported natively in Python 3.9 – 3.12 by combining the `@classmethod` and `@property`
+decorators, is that unfortunately unless a custom metaclass is used to intervene, class
+properties can be overwritten by value assignment.
+
+This is a result of differences in Python's handling for descriptors between classes and
+instances of classes. For both classes and instances, the `__get__` descriptor is called
+while the `__set__` and `__delete__` descriptor methods will only be called on instances
+such that we have no way to be involved in the property reassignment or deletion process
+as would be the case for properties on instances where we can create our own setter and
+deleter methods in addition to the getter.
+
+This caveat can be remedied through a custom metaclass however, which overrides default
+behaviour, and is able to intercept the `__setattr_` and `__delattr__` calls as needed.
+
+```python
+from classicist import classproperty
+
+class exampleclass(object):
+    @classproperty
+    def greeting(cls) -> str:
+        # Generate a return value here
+        return "hello"
+
+# We can access `.greeting` as though it was defined as a property:
+assert exampleclass.greeting == "hello"
+
+# Note: The `.greeting` property will be reassigned to the new value, "goodbye":
+exampleclass.greeting = "goodbye"
+assert exampleclass.greeting == "goodbye"
+```
+
+As can be seen with the method of natively supporting class properties, they could also
+have their values reassigned without warning:
+
+```python
+import sys
+import pytest
+
+# As Python only natively supported combining @classmethod and @property between version
+# 3.9 and 3.12, the example below is not usable on other versions, such as 3.13+
+if sys.version_info.major == 3 and not (9 <= sys.version_info.minor <= 12):
+    pytest.skip("This test can run on Python versions 3.9 – 3.12")
+
+class exampleclass(object):
+    @classmethod
+    @property
+    def greeting(cls) -> str:
+        # Generate a return value here
+        return "hello"
+
+# We can access `.greeting` as though it was defined as a property:
+assert exampleclass.greeting == "hello"
+
+# Note: The `.greeting` property will be reassigned to the new value, "goodbye":
+exampleclass.greeting = "goodbye"
+assert exampleclass.greeting == "goodbye"
+```
+
+### Unit Tests
+
+The Classicist library includes a suite of comprehensive unit tests which ensure that
+the library functionality operates as expected. The unit tests were developed with and
+are run via `pytest`.
+
+To ensure that the unit tests are run within a predictable runtime environment where all of the necessary dependencies are available, a [Docker](https://www.docker.com) image is created within which the tests are run. To run the unit tests, ensure Docker and Docker Compose is [installed](https://docs.docker.com/engine/install/), and perform the following commands, which will build the Docker image via `docker compose build` and then run the tests via `docker compose run` – the output of running the tests will be displayed:
+
+```shell
+$ docker compose build
+$ docker compose run tests
+```
+
+To run the unit tests with optional command line arguments being passed to `pytest`, append the relevant arguments to the `docker compose run tests` command, as follows, for example passing `-vv` to enable verbose output:
+
+```shell
+$ docker compose run tests -vv
+```
+
+See the documentation for [PyTest](https://docs.pytest.org/en/latest/) regarding available optional command line arguments.
+
+### Copyright & License Information
+
+Copyright © 2025 Daniel Sissman; licensed under the MIT License.

classicist-1.0.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "classicist"
+description = "Classy class decorators for Python."
+readme = {file = "README.md", content-type = "text/markdown"}
+keywords = ["decorator", "hybrid method", "class method", "instance method", "class property", "class properties"]
+authors = [{name = "Daniel Sissman"}]
+license = "MIT"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+requires-python = ">=3.10"
+dynamic = [
+  "version",
+  "dependencies",
+  "optional-dependencies",
+]
+
+[project.urls]
+documentation = "https://github.com/bluebinary/classicist/blob/main/README.md"
+changelog = "https://github.com/bluebinary/classicist/blob/main/CHANGELOG.md"
+repository = "https://github.com/bluebinary/classicist"
+issues = "https://github.com/bluebinary/classicist/issues"
+homepage = "https://github.com/bluebinary/classicist"
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.dynamic]
+version = {file = "source/classicist/version.txt"}
+dependencies = {file = "requirements.txt"}
+
+[tool.setuptools.dynamic.optional-dependencies]
+development = {file = "requirements.development.txt"}
+distribution = {file = "requirements.distribution.txt"}
+
+[tool.setuptools]
+zip-safe = true
+include-package-data = true
+
+[tool.setuptools.packages]
+find = {where = ["source"]}
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "-ra -q"
+testpaths = [
+    "tests"
+]
+
+[tool.black]
+line-length = 88
+target-version = ['py310']
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  # The following are specific to Black, you probably don't want those.
+  | blib2to3
+  | tests/data
+  | profiling
+)/
+'''

classicist-1.0.0/requirements.development.txt

@@ -0,0 +1,4 @@
+# Classicist Library: Development & Test Dependencies
+black==24.10.*
+pytest==8.3.*
+pytest-codeblocks==0.17.0

classicist-1.0.0/requirements.distribution.txt

@@ -0,0 +1,4 @@
+# Classicist Library: Build & Distribution Dependencies
+build
+twine
+wheel

classicist-1.0.0/requirements.txt

@@ -0,0 +1 @@
+# Classicist Library: Runtime Dependencies

classicist-1.0.0/setup.cfg

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

classicist-1.0.0/source/classicist/__init__.py

@@ -0,0 +1,118 @@
+import logging
+
+
+logger = logging.getLogger(__name__)
+
+
+class hybridmethod(object):
+    """The 'hybridmethod' decorator allows a method to be used as both a class method
+    and an instance method. The hybridmethod class decorator can wrap methods defined
+    in classes using the usual @decorator syntax. Methods defined in classes that are
+    decorated with the @hybridmethod decorator can be accessed as both class methods
+    and as instance methods, with the first argument passed to the method being the
+    reference to either the class when the method is called as a class method or to
+    the instance when the method is called as an instance method.
+
+    A check of the value of the first variable using isinstance(<variable>, <class>) can
+    be used within a hybrid method to determine if the call was made on an instance of
+    the class in which case the isinstance() call would evalute to True or if the call
+    was made on the class itself, in which case isinstance() would evaluate to False.
+    The variable passed as the first argument to the method may have any name, including
+    'self', as in Python, the use of 'self' as the name of the first argument on an
+    instance method is just customary and the name has no significance like it does in
+    other languages where the reference to the instance is provided automatically and
+    may go by 'self', 'this' or something else."""
+
+    def __init__(self, function: callable):
+        logger.debug(
+            "%s.__init__(function: %s)",
+            self.__class__.__name__,
+            function,
+        )
+
+        if not callable(function):
+            raise TypeError(
+                "The '%s' decorator can only be used to wrap callables!"
+                % (self.__class__.__name__)
+            )
+        elif not type(function).__name__ == "function":
+            raise TypeError(
+                "The '%s' decorator can only be used to wrap functions!"
+                % (self.__class__.__name__)
+            )
+
+        self.function: callable = function
+
+    def __get__(self, instance, owner) -> callable:
+        logger.debug(
+            "%s.__get__(self: %s, instance: %s, owner: %s)",
+            self.__class__.__name__,
+            self,
+            instance,
+            owner,
+        )
+
+        if instance is None:
+            return lambda *args, **kwargs: self.function(owner, *args, **kwargs)
+        else:
+            return lambda *args, **kwargs: self.function(instance, *args, **kwargs)
+
+
+class classproperty(property):
+    """The classproperty decorator transforms a method into a class-level property. This
+    provides access to the method as if it were a class attribute; this addresses the
+    removal of support for combining the @classmethod and @property decorators to create
+    class properties in Python 3.13, a change which was made due to some complexity in
+    the underlying interpreter implementation."""
+
+    def __init__(self, fget: callable, fset: callable = None, fdel: callable = None):
+        super().__init__(fget, fset, fdel)
+
+    def __get__(self, instance: object, klass: type = None):
+        if klass is None:
+            return self
+        return self.fget(klass)
+
+    def __set__(self, instance: object, value: object):
+        # Note that the __set__ descriptor cannot be used on class methods unless
+        # the class is created with a metaclass that implements this behaviour
+        raise NotImplemented
+
+    def __delete__(self, instance: object):
+        # Note that the __delete__ descriptor cannot be used on class methods unless
+        # the class is created with a metaclass that implements this behaviour
+        raise NotImplemented
+
+    def __getattr__(self, name: str):
+        if name in ATTRIBUTES:
+            return getattr(self.fget, name)
+        else:
+            raise AttributeError(
+                "The classproperty method '%s' does not have an '%s' attribute!"
+                % (
+                    self.fget.__name__,
+                    name,
+                )
+            )
+
+    # # For inspectability, provide access to the underlying function's metadata
+    # # including __module__, __name__, __qualname__, __doc__, and __annotations__
+    # @property
+    # def __module__(self):
+    #     return self.fget.__module__
+    #
+    # @property
+    # def __name__(self):
+    #     return self.fget.__name__
+    #
+    # @property
+    # def __qualname__(self):
+    #     return self.fget.__qualname__
+    #
+    # @property
+    # def __doc__(self):
+    #     return self.fget.__doc__
+    #
+    # @property
+    # def __annotations__(self):
+    #     return self.fget.__annotations__

classicist-1.0.0/source/classicist/version.txt

@@ -0,0 +1 @@
+1.0.0

classicist-1.0.0/source/classicist.egg-info/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: classicist
+Version: 1.0.0
+Summary: Classy class decorators for Python.
+Author: Daniel Sissman
+License-Expression: MIT
+Project-URL: documentation, https://github.com/bluebinary/classicist/blob/main/README.md
+Project-URL: changelog, https://github.com/bluebinary/classicist/blob/main/CHANGELOG.md
+Project-URL: repository, https://github.com/bluebinary/classicist
+Project-URL: issues, https://github.com/bluebinary/classicist/issues
+Project-URL: homepage, https://github.com/bluebinary/classicist
+Keywords: decorator,hybrid method,class method,instance method,class property,class properties
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Provides-Extra: development
+Requires-Dist: black==24.10.*; extra == "development"
+Requires-Dist: pytest==8.3.*; extra == "development"
+Requires-Dist: pytest-codeblocks==0.17.0; extra == "development"
+Provides-Extra: distribution
+Requires-Dist: build; extra == "distribution"
+Requires-Dist: twine; extra == "distribution"
+Requires-Dist: wheel; extra == "distribution"
+Dynamic: license-file
+
+# Classicist: Classy Class Decorators & Extensions
+
+The Classicist library provides several useful class decorators for Python class methods
+including a `hybridmethod` decorator that allows methods defined in a class to be used
+both a class method and an instance method, and a `classproperty` decorator that allows
+class methods to be accessed as class properties.
+
+The `classicist` library was previously named `hybridmethod` so if a prior version had been
+installed, please update references to the new library name. Installation of the
+library via its old name, `hybridmethod`, will install the new `classicist` library with
+a mapping for backwards compatibility so that code continues to function as before.
+
+### Requirements
+
+The Classicist library has been tested with Python 3.9, 3.10, 3.11, 3.12 and 3.13. The library is not compatible with Python 3.8 or earlier.
+
+### Installation
+
+The Classicist library is available from PyPI, so may be added to a project's dependencies via its `requirements.txt` file or similar by referencing the Classicist library's name, `classicist`, or the library may be installed directly into your local runtime environment using `pip` via the `pip install` command by entering the following into your shell:
+
+	$ pip install classicist
+
+#### Hybrid Methods
+
+The Classicist library provides a `hybridmethod` method decorator that allows methods
+defined in a class to be used as both a class method and an instance method.
+
+The `@hybridmethod` decorator provided by the library wraps methods defined in classes
+using the usual `@decorator` syntax. Methods defined in classes that are decorated with
+the `@hybridmethod` decorator can then be accessed as both class methods and as instance
+methods, with the first argument passed to the method being a reference to either the
+class when the method is called as a class method or to the instance when the method is
+called as an instance method.
+
+If a class-level property is defined and then an instance-level property is created with
+the same name that shadows the class-level property, the hybrid method can be used to
+interact with both the class-level property and the instance-level property simply based
+on whether the hybrid method was called directly on the class or on an a class instance.
+
+If desired, a simple check of the value of the first variable passed to a hybrid method
+using `isinstance(<variable>, <class>)` allows one to determine if the call was made on
+an instance of the class in which case `isinstance()` evaluates to `True` or if the call
+was made on the class itself, in which case `isinstance()` evaluates to `False`.
+
+The variable passed as the first argument to the method may have any name, including as
+is common in Python, `self`, although the use of `self` as the name of this argument on
+an instance method is just customary and the name has no significance.
+
+If using the `isinstance(<variable>, <class>)` check as described above is used simply
+substitute in the name of the first variable of a hybrid method for `<variable>` and the
+name of the class for `<class>`.
+
+#### Hybrid Methods: Usage
+
+To use the `hybridmethod` decorator import the decorator from the `classicist` library
+and use it to decorate the class methods you wish to use as both class methods and
+instance methods:
+
+```python
+from classicist import hybridmethod
+
+class hybridcollection(object):
+    items: list[str] = []
+
+    def __init__(self):
+        # Create an 'items' instance variable; note that this shadows the class variable
+        # of the same name which can still be accessed directly via self.__class__.items
+        self.items: list[object] = []
+
+    @hybridmethod
+    def add_item(self, item: object):
+        # We can use the following line to differentiate between the call being made on
+        # an instance or directly on the class; isinstance(self, <class>) returns True
+        # if the method was called on an instance of the class, or False if the method
+        # was called on the class directly; the 'self' variable will reference either
+        # the instance or the class; although 'self' is traditionally used in Python as
+        # reference to the instance
+        if isinstance(self, hybridcollection):
+            self.items.append(item)
+        else:
+            self.items.append(item)
+
+    def get_class_items(self) -> list[object]:
+        return self.__class__.items
+
+    def get_instance_items(self) -> list[object]:
+        return self.items
+
+    def get_combined_items(self) -> list[object]:
+        return self.__class__.items + self.items
+
+hybridcollection.add_item("ABC")  # Add an item to the class-level items list
+
+collection = hybridcollection()
+
+collection.add_item("XYZ")  # Add an item to the instance-level items list
+
+assert collection.get_class_items() == ["ABC"]
+
+assert collection.get_instance_items() == ["XYZ"]
+
+assert collection.get_combined_items() == ["ABC", "XYZ"]
+```
+
+#### Class Properties
+
+The Classicist library provides a `classproperty` method decorator that allows class
+methods to be accessed as class properties.
+
+The `@classproperty` decorator provided by the library wraps methods defined in classes
+using the usual `@decorator` syntax. Methods defined in classes that are decorated with
+the `@classproperty` decorator can then be accessed as though they were real properties
+on the class.
+
+The `@classproperty` decorator addresses the removal in Python 3.13 of the prior support
+for combining the `@classmethod` and `@property` decorators to create class properties,
+a change which was made due to complexity in the underlying interpreter implementation.
+
+#### Class Properties: Usage
+
+To use the `classproperty` decorator import the decorator from the `classicist` library
+and use it to decorate any class methods you wish to access as class properties.
+
+```python
+from classicist import classproperty
+
+class exampleclass(object):
+    @classproperty
+    def greeting(cls) -> str:
+        """The 'greeting' class method has been decorated with classproperty so acts as
+        a property; here we could do some work to generate a return value."""
+        return "hello"
+
+assert isinstance(exampleclass, type)
+assert issubclass(exampleclass, exampleclass)
+assert issubclass(exampleclass, object)
+
+# We can access `.greeting` as though it was defined as a property:
+# The return value of `.greeting` is indiscernible from the value being returned
+assert isinstance(exampleclass.greeting, str)
+assert exampleclass.greeting == "hello"
+```
+
+⚠️ An important caveat regarding class properties which applies equally to the method of
+supporting class properties provided by this library, and to class properties which are
+supported natively in Python 3.9 – 3.12 by combining the `@classmethod` and `@property`
+decorators, is that unfortunately unless a custom metaclass is used to intervene, class
+properties can be overwritten by value assignment.
+
+This is a result of differences in Python's handling for descriptors between classes and
+instances of classes. For both classes and instances, the `__get__` descriptor is called
+while the `__set__` and `__delete__` descriptor methods will only be called on instances
+such that we have no way to be involved in the property reassignment or deletion process
+as would be the case for properties on instances where we can create our own setter and
+deleter methods in addition to the getter.
+
+This caveat can be remedied through a custom metaclass however, which overrides default
+behaviour, and is able to intercept the `__setattr_` and `__delattr__` calls as needed.
+
+```python
+from classicist import classproperty
+
+class exampleclass(object):
+    @classproperty
+    def greeting(cls) -> str:
+        # Generate a return value here
+        return "hello"
+
+# We can access `.greeting` as though it was defined as a property:
+assert exampleclass.greeting == "hello"
+
+# Note: The `.greeting` property will be reassigned to the new value, "goodbye":
+exampleclass.greeting = "goodbye"
+assert exampleclass.greeting == "goodbye"
+```
+
+As can be seen with the method of natively supporting class properties, they could also
+have their values reassigned without warning:
+
+```python
+import sys
+import pytest
+
+# As Python only natively supported combining @classmethod and @property between version
+# 3.9 and 3.12, the example below is not usable on other versions, such as 3.13+
+if sys.version_info.major == 3 and not (9 <= sys.version_info.minor <= 12):
+    pytest.skip("This test can run on Python versions 3.9 – 3.12")
+
+class exampleclass(object):
+    @classmethod
+    @property
+    def greeting(cls) -> str:
+        # Generate a return value here
+        return "hello"
+
+# We can access `.greeting` as though it was defined as a property:
+assert exampleclass.greeting == "hello"
+
+# Note: The `.greeting` property will be reassigned to the new value, "goodbye":
+exampleclass.greeting = "goodbye"
+assert exampleclass.greeting == "goodbye"
+```
+
+### Unit Tests
+
+The Classicist library includes a suite of comprehensive unit tests which ensure that
+the library functionality operates as expected. The unit tests were developed with and
+are run via `pytest`.
+
+To ensure that the unit tests are run within a predictable runtime environment where all of the necessary dependencies are available, a [Docker](https://www.docker.com) image is created within which the tests are run. To run the unit tests, ensure Docker and Docker Compose is [installed](https://docs.docker.com/engine/install/), and perform the following commands, which will build the Docker image via `docker compose build` and then run the tests via `docker compose run` – the output of running the tests will be displayed:
+
+```shell
+$ docker compose build
+$ docker compose run tests
+```
+
+To run the unit tests with optional command line arguments being passed to `pytest`, append the relevant arguments to the `docker compose run tests` command, as follows, for example passing `-vv` to enable verbose output:
+
+```shell
+$ docker compose run tests -vv
+```
+
+See the documentation for [PyTest](https://docs.pytest.org/en/latest/) regarding available optional command line arguments.
+
+### Copyright & License Information
+
+Copyright © 2025 Daniel Sissman; licensed under the MIT License.

classicist-1.0.0/source/classicist.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE.md
+README.md
+pyproject.toml
+requirements.development.txt
+requirements.distribution.txt
+requirements.txt
+source/classicist/__init__.py
+source/classicist/version.txt
+source/classicist.egg-info/PKG-INFO
+source/classicist.egg-info/SOURCES.txt
+source/classicist.egg-info/dependency_links.txt
+source/classicist.egg-info/requires.txt
+source/classicist.egg-info/top_level.txt
+source/classicist.egg-info/zip-safe
+tests/test_classproperty.py
+tests/test_hybridmethod.py

classicist-1.0.0/source/classicist.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

classicist-1.0.0/source/classicist.egg-info/requires.txt

@@ -0,0 +1,10 @@
+
+[development]
+black==24.10.*
+pytest==8.3.*
+pytest-codeblocks==0.17.0
+
+[distribution]
+build
+twine
+wheel

classicist-1.0.0/source/classicist.egg-info/top_level.txt

@@ -0,0 +1 @@
+classicist

classicist-1.0.0/source/classicist.egg-info/zip-safe

@@ -0,0 +1 @@
+

classicist-1.0.0/tests/test_classproperty.py

@@ -0,0 +1,33 @@
+import pytest
+
+from classicist import classproperty
+
+
+@pytest.fixture(scope="module", name="exampleclass")
+def test_classproperty_fixture() -> type:
+    class exampleclass(object):
+        @classproperty
+        def name(cls) -> str:
+            return cls.__name__
+
+    return exampleclass
+
+
+def test_classproperty(exampleclass: type):
+    """Test the classproperty decorator on a demonstration class."""
+
+    assert isinstance(exampleclass, type)
+    assert issubclass(exampleclass, exampleclass)
+
+    assert isinstance(exampleclass.name, str)
+    assert exampleclass.name == "exampleclass"
+
+
+def test_classproperty_overwrite(exampleclass: type):
+    # Unfortunately without a metaclass to intervene, classproperties can be overwritten
+    # as although Python automatically calls the __get__ descriptor method it will not
+    # automatically call the __set__ or __delete__ descriptor methods on classes, so we
+    # have no way to prevent the property being reassigned unless a metaclass is used to
+    # intervene and provide behaviour we had previously with @classmethod and @property
+    exampleclass.name = "hello"
+    assert exampleclass.name == "hello"

classicist-1.0.0/tests/test_hybridmethod.py

@@ -0,0 +1,148 @@
+import pytest
+
+from classicist import hybridmethod
+
+
+@pytest.fixture(scope="module", name="hybridcollection")
+def test_hybridmethod_fixture() -> type:
+    """Test the hybridmethod decorator on the 'hybridcollection' demonstration class."""
+
+    class hybridcollection(object):
+        """This sample class provides hybrid methods that allow items to be added to and
+        removed from the class-level list and item-level list without needing to define
+        separate methods to manage the lists. The class also provides helper methods for
+        accessing the class-level list, instance-level list, and a combined list."""
+
+        items: list[object] = []
+
+        def __init__(self):
+            # Create an 'items' instance variable; note this shadows the class variable
+            # of the same name which can still be accessed via self.__class__.items
+            self.items: list[str] = []
+
+        @hybridmethod
+        def add_item(self, item: object):
+            # We can use the following line to differentiate between the call being made
+            # on an instance or directly on the class; isinstance(self, <class>) returns
+            # True if the method was called on an instance of the class, or False if the
+            # method was called on the class directly; the variable 'self' references
+            # either the instance or the class; although 'self' is traditionally used in
+            # Python as reference to the instance; the variable can be named anything:
+            if isinstance(self, hybridcollection):
+                self.items.append(item)
+            else:
+                self.items.append(item)
+
+        @hybridmethod
+        def remove_item(self, item: object):
+            if (index := self.items.index(item)) >= 0:
+                del self.items[index]
+
+        def get_class_items(self) -> list[object]:
+            return self.__class__.items
+
+        def get_instance_items(self) -> list[object]:
+            return self.items
+
+        def get_combined_items(self) -> list[object]:
+            return self.__class__.items + self.items
+
+    return hybridcollection
+
+
+def test_hybridmethod(hybridcollection: type):
+    """Test the hybridmethod decorator through an example use case of a class providing
+    access to a class-level list and instance-level list that are separately held in
+    memory and can be added to and removed from without affecting the other, while also
+    offering a method that returns a combined list of the items held in both lists."""
+
+    # Ensure that the hybridcollection type is of the expected type
+    assert isinstance(hybridcollection, type)
+
+    # Ensure that the hybridcollection type has an items list
+    assert isinstance(hybridcollection.items, list)
+
+    # Ensure that the class' items list is empty to begin with
+    assert len(hybridcollection.items) == 0
+
+    # Add an item to the class' items list
+    hybridcollection.add_item("ABC")
+
+    # Ensure that the class' items list length now reflects the newly added item
+    assert len(hybridcollection.items) == 1
+
+    # Ensure that the class' items list has the expected contents
+    assert hybridcollection.items == ["ABC"]
+
+    # Create an instance of the class
+    collection = hybridcollection()
+
+    # Ensure that the instance is of the expected type
+    assert isinstance(collection, hybridcollection)
+
+    # Ensure that the instance has an items list
+    assert isinstance(collection.items, list)
+
+    # Ensure that the instance's items list is empty
+    assert len(collection.items) == 0
+
+    # Add an item to the instance's item list
+    collection.add_item("XYZ")
+
+    # Ensure that the instance's items list length now reflects the newly added item
+    assert len(collection.items) == 1
+
+    # Ensure that the instance's items list has the expected contents
+    assert collection.items == ["XYZ"]
+
+    # Ensure that the instance's items list has the expected contents, in this case
+    # as accessed via the class' get_instance_items helper method:
+    assert collection.get_instance_items() == ["XYZ"]
+
+    # Ensure that the class' items list still has the expected contents and was not
+    # affected by the addition of an item to the instance's items list, in this case
+    # as accessed via the class reference on the instance:
+    assert collection.__class__.items == ["ABC"]
+
+    # Ensure that the class' items list still has the expected contents and was not
+    # affected by the addition of an item to the instance's items list, in this case
+    # as accessed via the class' get_class_items helper method:
+    assert collection.get_class_items() == ["ABC"]
+
+    # Ensure that the combined items held in the class' and the instance's items list
+    # are as expected, in this case as accessed via the items lists directly:
+    assert collection.__class__.items + collection.items == ["ABC", "XYZ"]
+
+    # Ensure that the combined items held in the class' and the instance's items list
+    # are as expected, in this case accessed via the get_combined_items helper method:
+    assert collection.get_combined_items() == ["ABC", "XYZ"]
+
+    # Add another item to the instance's item list
+    collection.add_item(123)
+
+    # Ensure that the class' items list still contains the expected number of items
+    assert len(hybridcollection.items) == 1
+
+    # Ensure that the class' items list still contains the expected items
+    assert hybridcollection.items == ["ABC"]
+
+    # Ensure that the instance's items list contains the expected number of items
+    assert len(collection.items) == 2
+
+    # Ensure that the instance's items list contains the expected items
+    assert collection.items == ["XYZ", 123]
+
+    # Remove an item from the list
+    collection.remove_item("XYZ")
+
+    # Ensure that the instance's items list contains the expected number of items
+    assert len(collection.items) == 1
+
+    # Ensure that the instance's items list contains the expected items
+    assert collection.items == [123]
+
+    # Ensure that the class' items list still contains the expected number of items
+    assert len(hybridcollection.items) == 1
+
+    # Ensure that the class' items list still contains the expected items
+    assert hybridcollection.items == ["ABC"]