classicist 1.0.0__py3-none-any.whl

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/version.txt

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

classicist-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+classicist/__init__.py,sha256=_pJXZUnA8U2nAlOZ3qIlX0f1SKlyRrjVQjxX8JRiTCk,4649
+classicist/version.txt,sha256=klIfw8vZZL3J9YSpkbif3apXVO0cyW1tQkRTOGacEwU,5
+classicist-1.0.0.dist-info/licenses/LICENSE.md,sha256=qBmrjPmSCp0YFyaIl2G3FU3rniFD31YC0Yd3MrO1wEg,1070
+classicist-1.0.0.dist-info/METADATA,sha256=f0HnAwDPgxgj4qWsxQWnEcIpcJaX7cKsjQCuRH7RywA,11600
+classicist-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+classicist-1.0.0.dist-info/top_level.txt,sha256=beG3ZuwObnmnY_mgNSN5CaVIWpI2VKszjVdKHPgZBhc,11
+classicist-1.0.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+classicist-1.0.0.dist-info/RECORD,,

classicist-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

classicist-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

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

classicist-1.0.0.dist-info/zip-safe

@@ -0,0 +1 @@
+