classicist 1.0.3__py3-none-any.whl → 1.0.5__py3-none-any.whl

classicist/__init__.py

@@ -1,20 +1,39 @@
-# Decorator Classes
+# Decorators
 from classicist.decorators import (
+    # @alias decorator
     alias,
-    annotate,
+    # @annotation decorator
     annotation,
-    annotations,
+    # @classproperty decorator
     classproperty,
+    # @deprecated decorator
     deprecated,
+    # @hybridmethod decorator
     hybridmethod,
+    # @nocache decorator
     nocache,
+    # @runtimer decorator
+    runtimer,
 )
 
 # Decorator Helper Methods
 from classicist.decorators import (
+    # @alias decorator helper methods
     is_aliased,
     aliases,
+    # @annotation decorator helper methods
+    annotate,
+    annotations,
+    # @deprecated decorator helper methods
     is_deprecated,
+    # @runtimer decorator helper methods
+    runtime,
+    has_runtimer,
+)
+
+# Decorator Related Classes
+from classicist.decorators import (
+    Runtimer,
 )
 
 # Meta Classes
@@ -25,9 +44,16 @@ from classicist.metaclasses import (
 
 # Exception Classes
 from classicist.exceptions import (
+    AliasError,
+    AnnotationError,
     AttributeShadowingError,
 )
 
+from classicist.types import (
+    NullType,
+    Null,
+)
+
 __all__ = [
     # Decorators
     "alias",
@@ -38,13 +64,23 @@ __all__ = [
     "deprecated",
     "hybridmethod",
     "nocache",
+    "runtimer",
     # Decorator Helper Methods
     "is_aliased",
     "aliases",
     "is_deprecated",
+    "runtime",
+    "has_runtimer",
+    # Decorator Related Classes
+    "Runtimer",
     # Meta Classes
     "aliased",
     "shadowproof",
     # Exception Classes
+    "AliasError",
+    "AnnotationError",
     "AttributeShadowingError",
+    # Types
+    "NullType",
+    "Null",
 ]

classicist/decorators/__init__.py

@@ -4,6 +4,7 @@ from classicist.decorators.classproperty import classproperty
 from classicist.decorators.deprecated import deprecated, is_deprecated
 from classicist.decorators.hybridmethod import hybridmethod
 from classicist.decorators.nocache import nocache
+from classicist.decorators.runtimer import Runtimer, runtimer, runtime, has_runtimer
 
 __all__ = [
     "alias",
@@ -17,4 +18,8 @@ __all__ = [
     "is_deprecated",
     "hybridmethod",
     "nocache",
+    "Runtimer",
+    "runtimer",
+    "runtime",
+    "has_runtimer",
 ]

classicist/decorators/runtimer/__init__.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from functools import wraps
+from inspect import unwrap
+
+from classicist.logging import logger
+
+logger = logger.getChild(__name__)
+
+
+class Runtimer(object):
+    """The Runtimer class times and tracks the runtime of function calls."""
+
+    _funcobj: callable = None
+    _started: datetime = None
+    _stopped: datetime = None
+
+    def __init__(self, function: callable):
+        """Supports instantiating an instance of the Runtimer class."""
+
+        if not callable(function):
+            raise TypeError("The 'function' argument must reference a callable!")
+
+        self._funcobj = function
+
+    def __str__(self) -> str:
+        """Returns a string representation of the current Runtimer instance."""
+
+        return f"<{self.__class__.__name__}(started: {self.started}, stopped: {self.stopped}, duration: {self.duration})>"
+
+    def __repr__(self) -> str:
+        """Returns a debug string representation of the current Runtimer instance."""
+
+        return f"<{self.__class__.__name__}(started: {self.started}, stopped: {self.stopped}, duration: {self.duration}) @ {hex(id(self))}>"
+
+    def reset(self) -> Runtimer:
+        """Supports resetting the Runtimer timing information."""
+
+        self._started = None
+        self._stopped = None
+
+        return self
+
+    def start(self) -> Runtimer:
+        """Supports starting the Runtimer timer by recording the current datetime."""
+
+        self._started = datetime.now()
+        self._stopped = None
+
+        return self
+
+    def stop(self) -> Runtimer:
+        """Supports stopping the Runtimer timer by recording the current datetime."""
+
+        if self._started is None:
+            self._started = datetime.now()
+        self._stopped = datetime.now()
+
+        return self
+
+    @property
+    def function(self) -> callable:
+        """Supports returning the Runtimer instance's associated function/method."""
+
+        return self._funcobj
+
+    @property
+    def started(self) -> datetime:
+        """Supports returning the started datetime or the current time as a fallback."""
+
+        return self._started or datetime.now()
+
+    @property
+    def stopped(self) -> datetime:
+        """Supports returning the stopped datetime or the current time as a fallback."""
+
+        return self._stopped or datetime.now()
+
+    @property
+    def timedelta(self) -> timedelta:
+        """Supports returning the timedelta for the decorated function's call time."""
+
+        if isinstance(self._started, datetime) and isinstance(self._stopped, datetime):
+            return self._stopped - self._started
+        else:
+            return timedelta(0)
+
+    @property
+    def duration(self) -> float:
+        """Supports returning the duration of the decorated function's call time."""
+
+        return self.timedelta.total_seconds()
+
+
+def runtimer(function: callable) -> callable:
+    """The runtimer decorator method creates an instance of the Runtimer class for the
+    specified function, allowing calls to the function to be timed."""
+
+    if not callable(function):
+        raise TypeError("The 'function' argument must reference a callable!")
+
+    logger.debug("runtimer(function: %s)", function)
+
+    # If the function already has an associated Runtimer instance, reset it
+    if isinstance(
+        _runtimer := getattr(function, "_classicist_runtimer", None), Runtimer
+    ):
+        _runtimer.reset()
+    else:
+        # Otherwise, create a new instance and associate it with the function
+        _runtimer = function._classicist_runtimer = Runtimer(function)
+
+    @wraps(function)
+    def wrapper(*args, **kwargs):
+        logger.debug(
+            "runtimer(function: %s).wrapper(args: %s, kwargs: %s)",
+            function,
+            args,
+            kwargs,
+        )
+
+        _runtimer.start()
+        result = function(*args, **kwargs)
+        _runtimer.stop()
+
+        return result
+
+    return wrapper
+
+
+def runtime(function: callable) -> Runtimer | None:
+    """The runtime helper method can be used to obtain the Runtimer instance for the
+    specified function, if one is present, allowing access to the most recent function
+    call start and stop time stamps and call duration."""
+
+    if not callable(function):
+        raise TypeError("The 'function' argument must reference a callable!")
+
+    function = unwrap(function)
+
+    logger.debug("runtime(function: %s)" % (function))
+
+    if isinstance(
+        _runtimer := getattr(function, "_classicist_runtimer", None), Runtimer
+    ):
+        return _runtimer
+
+
+def has_runtimer(function: callable) -> bool:
+    """The has_runtimer helper method can be used to determine if the specified function
+    has an associated Runtimer instance or not, returning a boolean to indicate this."""
+
+    if isinstance(getattr(function, "_classicist_runtimer", None), Runtimer):
+        return True
+    else:
+        return False
+
+
+__all__ = [
+    "Runtimer",
+    "runtimer",
+    "runtime",
+    "hasruntimer",
+]

classicist/exceptions/__init__.py

@@ -1,4 +1,5 @@
 from classicist.exceptions.decorators import (
+    AliasError,
     AnnotationError,
 )
 
@@ -7,6 +8,7 @@ from classicist.exceptions.metaclasses import (
 )
 
 __all__ = [
+    "AliasError",
     "AnnotationError",
     "AttributeShadowingError",
 ]

classicist/types/__init__.py

@@ -0,0 +1,6 @@
+from classicist.types.null import NullType, Null
+
+__all__ = [
+    "NullType",
+    "Null",
+]

classicist/types/null/__init__.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+
+class NullType(object):
+    """The NullType class supports the creation of a Null singleton instance that offers
+    support for safely chaining nested attribute accesses without raising exceptions for
+    attributes that have no inherent value.
+
+    As Python currently lacks a null-aware navigation operator, such as `?.`, like many
+    other dynamic languages, for safely navigating nested object hierarchies which may
+    contain null attributes, the library offers the `NullType` and `Null` singleton as a
+    potential option to support this need in the interim. Consistent use of the `Null`
+    singleton in place of the standard `None` singleton, in relevant scenarios, such as
+    within a data model library for example, can allow for more expressive and clearer
+    code that does not require endless checks for intermediary attribute existence.
+
+    However, there are some caveats to the use of the `NullType` and `Null` singleton as
+    these are not built-in features of the language, and Python does not offer support
+    for the creation of custom operators nor overriding the `is` operator for identity
+    checking which limits some of the cases in which the `Null` singleton could be used.
+
+    With knowledge of the caveats and in the right scenarios, the `Null` singleton can
+    offer a good way to achieve clearer and more expressive code while navigating nested
+    object hierarchies without the clutter of nested attribute existence checks."""
+
+    _instance: NullType = None
+
+    def __new__(cls) -> NullType:
+        """Ensure NullType can only create a singleton instance; further calls to create
+        instances of the NullType will return the existing singleton instance."""
+
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+
+        return cls._instance
+
+    def __getattr__(self, name: str) -> NullType:
+        """Support nested attribute access by returning the singleton instance."""
+
+        return self.__class__._instance
+
+    def __bool__(self) -> bool:
+        """Support falsey equality checks for boolean comparisons against NullType."""
+
+        return False  # Always returns False
+
+    def __eq__(self, value: object) -> bool:
+        """Support value equality checks against NullType via the `==` operator as the
+        fallback option to being able to support identity equality checks via the `is`
+        operator which are not currently possible due to language constraints."""
+
+        if value is None or value is False:
+            return True
+        else:
+            return self is value
+
+    def __str__(self) -> str:
+        return "Null"
+
+    def __repr__(self) -> str:
+        return "Null"
+
+
+# Create the singleton instance of Null
+Null = NullType()
+
+__all__ = [
+    "NullType",
+    "Null",
+]

classicist/version.txt

@@ -1 +1 @@
-1.0.3
+1.0.5

{classicist-1.0.3.dist-info → classicist-1.0.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: classicist
-Version: 1.0.3
+Version: 1.0.5
 Summary: Classy class decorators for Python.
 Author: Daniel Sissman
 License-Expression: MIT
@@ -33,16 +33,20 @@ Dynamic: license-file
 
 # Classicist: Classy Class Decorators & Extensions
 
-The Classicist library provides several useful decorators and helper methods including:
+The Classicist library provides several useful decorators, functions, classes, and types
+that offer useful behaviours and functionality, and help to fill some of the gaps in the
+current standard library:
 
  * `@hybridmethod` – a decorator that allows methods to be used both as class methods and as instance methods;
- * `@classproperty` – a decorator that allow class methods to be accessed as class properties;
+ * `@classproperty` – a decorator that allows class methods to be accessed as class properties;
  * `@annotation` – a decorator that can be used to apply arbitrary annotations to code objects;
- * `@deprecated` – a decorator that can be used to mark functions, classes and methods as being deprecated;
+ * `@deprecated` – a decorator that can be used to mark functions, classes and methods as being deprecated, with support for adding optional arbitrary annotations;
  * `@alias` – a decorator that can be used to add aliases to classes, methods defined within classes, module-level functions, and nested functions when overriding the aliasing scope;
  * `@nocache` – a decorator that can be used to mark functions and methods as not being suitable for caching;
+ * `@runtimer` – a decorator that can be used to gather call run time information for function and method calls;
  * `shadowproof` – a metaclass that can be used to protect subclasses from class-level attributes
-  being overwritten (or shadowed) which can otherwise negatively affect class behaviour in some cases.
+  being overwritten (or shadowed) which can otherwise negatively affect class behaviour in some cases;
+* `Null` – an alternative to `None`, useful when building custom data model classes and libraries, where supporting "null-safe" style access and navigation of the model's nested hierarchy is preferred.
 
 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
@@ -482,6 +486,48 @@ class Test(object):
         pass
 ```
 
+#### Runtimer: Function & Method Call Timing
+
+The `@runtimer` decorator can be used to obtain run times for function and method calls,
+including the start and stop `datetime`, the `timedelta` and the duration in seconds.
+
+To collect timing information simply import the `runtimer` decorator from the library,
+and apply it to the function, class method or instance method that you wish to time, and
+after the call has been made, you can obtain the run time information from the function
+or method via the `classicist` library's `runtime` helper method, which provides access
+to an instance of the library's `Runtimer` class which is used to track the run time:
+
+```python
+from classicist import runtimer, runtime, Runtimer
+from datetime import datetime
+from time import sleep
+
+@runtimer
+def function_to_time(value: int) -> int:
+  sleep(0.01)
+  return value * 100
+
+# Obtain a reference to the function's Runtimer (created by the @runtimer decorator)
+# This reference can be obtained before or after a call to the decorated function
+runtimer: Runtimer = runtime(function_to_time)
+assert isinstance(runtimer, Runtimer)
+
+# Obtain the time before the function call for illustrative purposes (not needed in use)
+started: datetime = datetime.now()
+
+# Call the method to perform its work, and its runtime will be gathered
+assert function_to_time(2) == 200
+
+# Obtain the time after the function call for illustrative purposes (not needed in use)
+stopped: datetime = datetime.now()
+
+# Use the gathered runtime information as needed
+assert runtimer.started > started
+assert runtimer.duration >= 0.01
+assert runtimer.timedelta.total_seconds() >= 0.01
+assert runtimer.stopped < stopped
+```
+
 #### ShadowProof: Attribute Shadowing Protection Metaclass
 
 The `shadowproof` metaclass can be used to protect classes and subclasses from attribute
@@ -511,6 +557,146 @@ except AttributeShadowingError as exception:
     pass
 ```
 
+#### NullType: Null-Safe Style Access for Data Models and Nested Class Hierarchies
+
+The `NullType` class supports the creation of a `Null` singleton instance that offers
+support for safely chaining nested attribute accesses without raising exceptions for
+attributes that have no inherent value.
+
+As Python currently lacks a null-aware navigation operator, such as `?.`, unlike many
+other dynamic languages, for safely navigating nested object hierarchies which may
+contain null attributes, the library offers the `NullType` and `Null` singleton as a
+potential option to support this need in the interim. Consistent use of the `Null`
+singleton in place of the standard `None` singleton, in relevant scenarios, such as
+within a custom data model library, can allow for more expressive and clearer code that
+does not require endless checks for intermediary or nested attribute existence.
+
+However, there are some caveats to the use of the `NullType` and `Null` singleton as
+these are not built-in features of the language, and Python does not offer support for
+the creation of custom operators nor overriding the `is` operator for identity checking
+which limits some of the use cases in which the `Null` singleton can be used.
+
+With knowledge of these caveats and in the right scenarios, the `Null` singleton can
+offer a good way to achieve clearer and more expressive code while navigating nested
+object hierarchies without the clutter of nested attribute existence checks.
+
+```python
+from __future__ import annotations
+
+from classicist import Null
+
+data: dict = {
+  "id": 1,
+  "name": "A",
+  "related": {
+    "id": 2,
+    "name": "B",
+    "related": {
+      "id": 3,
+      "name": "C",
+    },
+  },
+}
+
+class Model(object):
+  """Sample Model class with some properties that reference nested Model instances."""
+
+  def __init__(self, data: dict):
+    if not isinstance(data, dict):
+      raise TypeError("The 'data' argument must reference a valid data dictionary!")
+
+    if not ("id" in data and isinstance(data["id"], int)):
+      raise ValueError("The 'data' must contain an 'id' key with an integer value!")
+
+    if not ("name" in data and isinstance(data["name"], str)):
+      raise ValueError("The 'data' must contain an 'name' key with an string value!")
+
+    self.data = data
+
+  @property
+  def id(self) -> int:
+    return self.data["id"]
+
+  @property
+  def name(self) -> str:
+    return self.data["name"]
+
+  @property
+  def related(self) -> Model | Null:
+    if data := self.data.get("related"):
+      return Model(data=data)
+    else:
+      return Null
+
+  @property
+  def relates(self) -> Model | Null:
+    if data := self.data.get("relates"):
+      return Model(data=data)
+    else:
+      return Null
+
+# Create an instance of the sample Model data class
+model = Model(data=data)
+
+# Check that the expected data attributes are available
+assert model.id == 1
+assert model.name == "A"
+
+# The model.related property references A/1 in the data above, so these properties exist
+assert model.related
+assert model.related.id
+assert model.related.name
+
+# Ensure the nested property values are as expected
+assert model.related.id == 2
+assert model.related.name == "B"
+
+# Note that model.relates had no corresponding data, so the Model returns `Null` which
+# still allows for nested attribute access, such as to `.id` and `.name` without raising
+# any exceptions; the `Null` singleton also allows for `bool` comparison as shown below:
+assert not model.relates
+assert not model.relates.id
+assert not model.relates.name
+
+# There is no limit to the levels of nesting that `NullType` and the `Null` singleton
+# can support, so long as a custom data model or library consistently returns `Null` for
+# cases where the "null-safe" navigation is desired:
+
+# model.related.related references 3/C in the data above, so these properties exist
+assert model.related.related.id
+assert model.related.related.name
+
+# model.related.relates was not specified in the data above so the Model returns `Null`
+assert not model.related.relates.id
+assert not model.related.relates.name
+
+# Ensure the nested property values are as expected
+assert model.related.related.id == 3
+assert model.related.related.name == "C"
+
+# These features make it easy to write clearer more expressive code without boilerplate
+# code to check for the availability of nested attributes or entities:
+if isinstance(name := model.related.name, str):
+  print("model.related.name => %s" % (name))
+
+# No exception is raised here even though model.relates is effectively "null":
+if isinstance(name := model.relates.name, str):
+  print("model.relates.name => %s" % (name))
+
+# However, there are some caveats as noted with `NullType` and the `Null` singleton as
+# these are a third-party solution so we can only go so far in supplementing null-safe
+# operator behaviour in the language; for example, we cannot perform identity checks to
+# boolean values, True or False, or the actual None singleton value:
+assert not model.relates is True  # Notice the `assert not` as `assert` would fail here
+assert not model.relates is False  # Notice the `assert not` as `assert` would fail here
+
+# Furthermore, we cannot use `None` identity comparison either:
+assert not model.relates is None  # Notice the `assert not` as `assert` would fail here
+
+# We can however perform an identity check against the `Null` singleton if needed:
+assert model.relates is Null
+```
+
 ### Unit Tests
 
 The Classicist library includes a suite of comprehensive unit tests which ensure that

{classicist-1.0.3.dist-info → classicist-1.0.5.dist-info}/RECORD

@@ -1,13 +1,14 @@
-classicist/__init__.py,sha256=Rkm1Vx0Z-BHPH1FSzFLrAxwkFEt1xvMxZz-mC8FJSDc,834
-classicist/version.txt,sha256=INLLCW0atBpBQCRtEvB79rjLdD_UgSK3JTLAPUTFwUo,5
-classicist/decorators/__init__.py,sha256=wplcs2JnyGMOh72626-x-WyVotVoT7nvk-dpjeTXQ88,600
+classicist/__init__.py,sha256=VeAO1fY3noKmFJDdiCFUABIykF3oXSk_9QXNSaaXIp0,1584
+classicist/version.txt,sha256=nXE_EpedYoeSULwKIDXj71cxWsQlHoUBnSHHXtcmlyA,5
+classicist/decorators/__init__.py,sha256=Cz1zXWoLV7s63pQiOQX6B0RGDOg3schTbtkq6THz3J8,752
 classicist/decorators/aliased/__init__.py,sha256=vW1P9jbGkOD_m9GvgEXF0Uni-Dt6rfVXDVF5D4wC1GY,6926
 classicist/decorators/annotation/__init__.py,sha256=20WwmrXDxT85sItpDiCdC-hZjbyDR6E2mLPMSKQgm8g,1796
 classicist/decorators/classproperty/__init__.py,sha256=ED37_20UeAGKX1ahsv16wTg0JAJT4UBLqiNRbKAp2KE,1646
 classicist/decorators/deprecated/__init__.py,sha256=aAPFQoT-pJf1nauQGiPADkPBREMvEQJaUQc3kjA48Rg,2764
 classicist/decorators/hybridmethod/__init__.py,sha256=uEsp54ZL0UESAbhIigLtzOg_DHupr9EohzZaL5VYJzY,2512
 classicist/decorators/nocache/__init__.py,sha256=0S2yToD_PjShQK8RZ_MZRBtBxGM6hegtDSIPbZlq4vw,287
-classicist/exceptions/__init__.py,sha256=JTo3DDfvL8eex0H5erL8Yd9pQL6B1l3nPXcCapcCWLs,219
+classicist/decorators/runtimer/__init__.py,sha256=3yoWDKzpq7IHrQJG2QMkUZOQmW4rtxmlM_mMC2N5V_8,4999
+classicist/exceptions/__init__.py,sha256=P4sVGQ5wn2wdNLAhKDBKfTX4Vgell6sPlAQhadcOJxw,253
 classicist/exceptions/decorators/__init__.py,sha256=YSpu4-sX0QKbLf0ZpNFS3hXA9pPOo3uoMgAFvRT3emc,192
 classicist/exceptions/decorators/aliased/__init__.py,sha256=ea8Q9TQ80r0DeRMBbJ9VX9Y3y00iTLYiuB2KEkW4ajw,43
 classicist/exceptions/decorators/annotation/__init__.py,sha256=nogEgpDo5lnEG7IC2kR4Pb_BORu6Cubik4LlcnCSg-g,48
@@ -18,9 +19,11 @@ classicist/logging/__init__.py,sha256=LJ-Nih1LacPrO2TvTT6l84So-pgw84AHJ8IhzYKl5r
 classicist/metaclasses/__init__.py,sha256=mYhR5rM7cnJlaNUlgoQWOo44RQSORteRjYd0y0BajxQ,159
 classicist/metaclasses/aliased/__init__.py,sha256=grs4Z8dMY6R2fCFn4UCPdCzEJtVaAv-tsWFwY1DCUpI,2033
 classicist/metaclasses/shadowproof/__init__.py,sha256=d55uNjcaCorD3MdDUv7aRVpk2MlE8JzMjint6Vvf_Yc,1492
-classicist-1.0.3.dist-info/licenses/LICENSE.md,sha256=qBmrjPmSCp0YFyaIl2G3FU3rniFD31YC0Yd3MrO1wEg,1070
-classicist-1.0.3.dist-info/METADATA,sha256=iZaQqjD9wd84Bb_Dx_Se-RMYgZTvvf2Hkf2idrnswgk,25128
-classicist-1.0.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-classicist-1.0.3.dist-info/top_level.txt,sha256=beG3ZuwObnmnY_mgNSN5CaVIWpI2VKszjVdKHPgZBhc,11
-classicist-1.0.3.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-classicist-1.0.3.dist-info/RECORD,,
+classicist/types/__init__.py,sha256=EZE6NnKf051F5MuqxyReJb4oHIzQY2gCgOxC51_64mI,92
+classicist/types/null/__init__.py,sha256=cY7eFop17KuuXO-1eqxXl1RGsAHASFKlpx5f7JXv00E,2829
+classicist-1.0.5.dist-info/licenses/LICENSE.md,sha256=qBmrjPmSCp0YFyaIl2G3FU3rniFD31YC0Yd3MrO1wEg,1070
+classicist-1.0.5.dist-info/METADATA,sha256=n9Dm7Vj8iWqws1XiuvRViMqoqsYiAV2gpCqvAGu0MEc,32691
+classicist-1.0.5.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+classicist-1.0.5.dist-info/top_level.txt,sha256=beG3ZuwObnmnY_mgNSN5CaVIWpI2VKszjVdKHPgZBhc,11
+classicist-1.0.5.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+classicist-1.0.5.dist-info/RECORD,,