classicist 1.0.2__tar.gz → 1.0.4__tar.gz

{classicist-1.0.2/source/classicist.egg-info → classicist-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: classicist
-Version: 1.0.2
+Version: 1.0.4
 Summary: Classy class decorators for Python.
 Author: Daniel Sissman
 License-Expression: MIT
@@ -39,8 +39,9 @@ The Classicist library provides several useful decorators and helper methods inc
  * `@classproperty` – a decorator that allow 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;
- * `@alias` – a decorator that can be used to add aliases to class methods;
+ * `@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 time 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.
 
@@ -263,32 +264,35 @@ exampleclass.greeting = "goodbye"
 assert exampleclass.greeting == "goodbye"
 ```
 
-#### Class Method Alias Decorator & Metaclass: Add Aliases to Methods
+#### Alias Decorator & Metaclass: Add Aliases to Classes, Methods & Functions
 
 The `@alias` decorator can be used to add aliases to classes, methods defined within
-classes, and module-level functions, such that both the original name and any defined
-aliases can be used to access the same code object at runtime.
+classes, module-level functions, and nested functions when overriding the aliasing scope,
+such that both the original name and any defined aliases can be used to access the same
+code object at runtime.
 
 To alias a class or a module-level function, that is a function defined at the top-level
 of a module file (rather than nested within a function or class), simply decorate the 
 class or module-level function with the `@alias(...)` decorator and specify the one or
-more name aliases for the code object as one or more string arguments passed into the
-decorator method.
+more name aliases for the class or function as one or more string arguments passed into
+the decorator method.
 
 To use the `@alias` decorator on methods defined within a class, it is also necessary to
 set the containing class' metaclass to the `aliased` metaclass provided by the `classicist`
-library; the metaclass iterates through the class namespace during parse time and sets up
+library; the metaclass iterates through the class' namespace during parse time and sets up
 the aliases as additional attributes on the class so that the aliased methods are available
-at runtime via both their original name and their aliases.
+at runtime via both their original name and any aliases.
 
-The example below demonstrates adding an alias to a method defined within a class, and
-using the `aliased` metaclass when defining the class to ensure that the alias is parsed
-and translated to an additional class attribute so that the method is accessible via its
-original name and the alias at runtime.
+The examples below demonstrate adding an alias to a module-level function, a class and a
+method defined within a class, and using the `aliased` metaclass when defining a class
+that contains aliased methods to ensure that any aliases are parsed and translated to
+additional class attributes so that the method is accessible via its original name and
+any alias at runtime.
 
-If control over the scope is required, the optional `scope` keyword argument can be
-used to specify the scope into which to apply the alias, this must be a reference to
-the globals() or locals() at the point in code where the `@alias()` decorator is used.
+If control over the scope is required, usually for nested functions, the optional `scope`
+keyword-only argument can be used to specify the scope into which to apply the alias; this
+must be a reference to `globals()` or `locals()` at the point in code where the `@alias(...)`
+decorator is applied to the nested function.
 
 ```python
 from classicist import aliased, alias, is_aliased, aliases
@@ -479,6 +483,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

{classicist-1.0.2 → classicist-1.0.4}/README.md

@@ -6,8 +6,9 @@ The Classicist library provides several useful decorators and helper methods inc
  * `@classproperty` – a decorator that allow 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;
- * `@alias` – a decorator that can be used to add aliases to class methods;
+ * `@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 time 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.
 
@@ -230,32 +231,35 @@ exampleclass.greeting = "goodbye"
 assert exampleclass.greeting == "goodbye"
 ```
 
-#### Class Method Alias Decorator & Metaclass: Add Aliases to Methods
+#### Alias Decorator & Metaclass: Add Aliases to Classes, Methods & Functions
 
 The `@alias` decorator can be used to add aliases to classes, methods defined within
-classes, and module-level functions, such that both the original name and any defined
-aliases can be used to access the same code object at runtime.
+classes, module-level functions, and nested functions when overriding the aliasing scope,
+such that both the original name and any defined aliases can be used to access the same
+code object at runtime.
 
 To alias a class or a module-level function, that is a function defined at the top-level
 of a module file (rather than nested within a function or class), simply decorate the 
 class or module-level function with the `@alias(...)` decorator and specify the one or
-more name aliases for the code object as one or more string arguments passed into the
-decorator method.
+more name aliases for the class or function as one or more string arguments passed into
+the decorator method.
 
 To use the `@alias` decorator on methods defined within a class, it is also necessary to
 set the containing class' metaclass to the `aliased` metaclass provided by the `classicist`
-library; the metaclass iterates through the class namespace during parse time and sets up
+library; the metaclass iterates through the class' namespace during parse time and sets up
 the aliases as additional attributes on the class so that the aliased methods are available
-at runtime via both their original name and their aliases.
+at runtime via both their original name and any aliases.
 
-The example below demonstrates adding an alias to a method defined within a class, and
-using the `aliased` metaclass when defining the class to ensure that the alias is parsed
-and translated to an additional class attribute so that the method is accessible via its
-original name and the alias at runtime.
+The examples below demonstrate adding an alias to a module-level function, a class and a
+method defined within a class, and using the `aliased` metaclass when defining a class
+that contains aliased methods to ensure that any aliases are parsed and translated to
+additional class attributes so that the method is accessible via its original name and
+any alias at runtime.
 
-If control over the scope is required, the optional `scope` keyword argument can be
-used to specify the scope into which to apply the alias, this must be a reference to
-the globals() or locals() at the point in code where the `@alias()` decorator is used.
+If control over the scope is required, usually for nested functions, the optional `scope`
+keyword-only argument can be used to specify the scope into which to apply the alias; this
+must be a reference to `globals()` or `locals()` at the point in code where the `@alias(...)`
+decorator is applied to the nested function.
 
 ```python
 from classicist import aliased, alias, is_aliased, aliases
@@ -446,6 +450,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

{classicist-1.0.2 → classicist-1.0.4}/source/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,6 +44,8 @@ from classicist.metaclasses import (
 
 # Exception Classes
 from classicist.exceptions import (
+    AliasError,
+    AnnotationError,
     AttributeShadowingError,
 )
 
@@ -38,13 +59,20 @@ __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",
 ]

{classicist-1.0.2 → classicist-1.0.4}/source/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-1.0.2 → classicist-1.0.4}/source/classicist/decorators/aliased/__init__.py

@@ -46,7 +46,7 @@ def alias(*names: tuple[str], scope: object = None) -> Callable:
 
         thing = unwrap(thing)
 
-        logger.info(f"@alias({names}) called on {thing}")
+        logger.debug(f"@alias({names}) called on {thing}")
 
         if isinstance(aliases := getattr(thing, "_classicist_aliases", None), tuple):
             setattr(thing, "_classicist_aliases", tuple([*aliases, *names]))
@@ -55,7 +55,7 @@ def alias(*names: tuple[str], scope: object = None) -> Callable:
 
         @wraps(thing)
         def wrapper_class(*args, **kwargs):
-            return thing  # (*args, **kwargs)
+            return thing
 
         @wraps(thing)
         def wrapper_method(*args, **kwargs):
@@ -63,7 +63,7 @@ def alias(*names: tuple[str], scope: object = None) -> Callable:
 
         @wraps(thing)
         def wrapper_function(*args, **kwargs):
-            return thing  # (*args, **kwargs)
+            return thing
 
         if inspect.isclass(thing):
             if not scope:
@@ -94,24 +94,18 @@ def alias(*names: tuple[str], scope: object = None) -> Callable:
             if not scope:
                 scope = sys.modules.get(thing.__module__ or "__main__")
 
-            if not scope:
-                logger.warning(f"No module found for {thing.__module__}!")
-
-                for module in sys.modules:
-                    logger.debug(f" => module => {module}")
-
-            # The qualified name for module-level functions only contain the name of the
-            # function, whereas functions nested within other functions or classes have
-            # names comprised of multiple parts separated by the "." character; because
-            # it is only currently possible to alias module-level functions, any nested
-            # or class methods are ignored during this stage of the aliasing process.
-            if len(thing.__qualname__.split(".")) > 1:
-                logger.warning(
-                    "Unable to apply alias to functions defined beyond the top-level of a module: %s!"
-                    % (thing.__qualname__)
-                )
+                # The qualified name for module-level functions only contain the name of the
+                # function, whereas functions nested within other functions or classes have
+                # names comprised of multiple parts separated by the "." character; because
+                # it is only currently possible to alias module-level functions, any nested
+                # or class methods are ignored during this stage of the aliasing process.
+                if len(thing.__qualname__.split(".")) > 1:
+                    logger.debug(
+                        "Unable to apply alias to functions defined beyond the top-level of a module: %s!"
+                        % (thing.__qualname__)
+                    )
 
-                return wrapper_function(*args, **kwargs)
+                    return wrapper_function(*args, **kwargs)
 
             # if signature := inspect.signature(thing):
             #     if len(parameters := signature.parameters) > 0 and "self" in parameters:
@@ -131,7 +125,7 @@ def alias(*names: tuple[str], scope: object = None) -> Callable:
                             )
                         )
 
-                    logger.info(f"Added alias '{name}' to {scope}.{thing}")
+                    logger.debug(f"Added alias '{name}' to {scope}.{thing}")
 
                     if isinstance(scope, dict):
                         scope[name] = thing
@@ -139,7 +133,7 @@ def alias(*names: tuple[str], scope: object = None) -> Callable:
                         setattr(scope, name, thing)
             else:
                 logger.warning(
-                    f"No scope was found or specified for {thing} into which to assign the alias!"
+                    f"No scope was found or specified for {thing} into which to assign aliases!"
                 )
 
             return wrapper_function(*args, **kwargs)

classicist-1.0.4/source/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-1.0.2 → classicist-1.0.4}/source/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-1.0.4/source/classicist/version.txt

@@ -0,0 +1 @@
+1.0.4

{classicist-1.0.2 → classicist-1.0.4/source/classicist.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: classicist
-Version: 1.0.2
+Version: 1.0.4
 Summary: Classy class decorators for Python.
 Author: Daniel Sissman
 License-Expression: MIT
@@ -39,8 +39,9 @@ The Classicist library provides several useful decorators and helper methods inc
  * `@classproperty` – a decorator that allow 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;
- * `@alias` – a decorator that can be used to add aliases to class methods;
+ * `@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 time 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.
 
@@ -263,32 +264,35 @@ exampleclass.greeting = "goodbye"
 assert exampleclass.greeting == "goodbye"
 ```
 
-#### Class Method Alias Decorator & Metaclass: Add Aliases to Methods
+#### Alias Decorator & Metaclass: Add Aliases to Classes, Methods & Functions
 
 The `@alias` decorator can be used to add aliases to classes, methods defined within
-classes, and module-level functions, such that both the original name and any defined
-aliases can be used to access the same code object at runtime.
+classes, module-level functions, and nested functions when overriding the aliasing scope,
+such that both the original name and any defined aliases can be used to access the same
+code object at runtime.
 
 To alias a class or a module-level function, that is a function defined at the top-level
 of a module file (rather than nested within a function or class), simply decorate the 
 class or module-level function with the `@alias(...)` decorator and specify the one or
-more name aliases for the code object as one or more string arguments passed into the
-decorator method.
+more name aliases for the class or function as one or more string arguments passed into
+the decorator method.
 
 To use the `@alias` decorator on methods defined within a class, it is also necessary to
 set the containing class' metaclass to the `aliased` metaclass provided by the `classicist`
-library; the metaclass iterates through the class namespace during parse time and sets up
+library; the metaclass iterates through the class' namespace during parse time and sets up
 the aliases as additional attributes on the class so that the aliased methods are available
-at runtime via both their original name and their aliases.
+at runtime via both their original name and any aliases.
 
-The example below demonstrates adding an alias to a method defined within a class, and
-using the `aliased` metaclass when defining the class to ensure that the alias is parsed
-and translated to an additional class attribute so that the method is accessible via its
-original name and the alias at runtime.
+The examples below demonstrate adding an alias to a module-level function, a class and a
+method defined within a class, and using the `aliased` metaclass when defining a class
+that contains aliased methods to ensure that any aliases are parsed and translated to
+additional class attributes so that the method is accessible via its original name and
+any alias at runtime.
 
-If control over the scope is required, the optional `scope` keyword argument can be
-used to specify the scope into which to apply the alias, this must be a reference to
-the globals() or locals() at the point in code where the `@alias()` decorator is used.
+If control over the scope is required, usually for nested functions, the optional `scope`
+keyword-only argument can be used to specify the scope into which to apply the alias; this
+must be a reference to `globals()` or `locals()` at the point in code where the `@alias(...)`
+decorator is applied to the nested function.
 
 ```python
 from classicist import aliased, alias, is_aliased, aliases
@@ -479,6 +483,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

{classicist-1.0.2 → classicist-1.0.4}/source/classicist.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ source/classicist/decorators/classproperty/__init__.py
 source/classicist/decorators/deprecated/__init__.py
 source/classicist/decorators/hybridmethod/__init__.py
 source/classicist/decorators/nocache/__init__.py
+source/classicist/decorators/runtimer/__init__.py
 source/classicist/exceptions/__init__.py
 source/classicist/exceptions/decorators/__init__.py
 source/classicist/exceptions/decorators/aliased/__init__.py
@@ -35,4 +36,5 @@ tests/test_annotation.py
 tests/test_classproperty.py
 tests/test_deprecated.py
 tests/test_hybridmethod.py
+tests/test_runtimer.py
 tests/test_shadowproof.py

classicist-1.0.4/tests/test_runtimer.py

@@ -0,0 +1,88 @@
+from classicist import Runtimer, runtimer, runtime, has_runtimer
+
+import time
+
+
+def test_runtimer_for_function():
+    """Test the runtimer for a function."""
+
+    @runtimer
+    def complex(value: int, sleep: float = 0.01) -> int:
+        time.sleep(sleep)
+        return value * 2
+
+    assert callable(complex)
+    assert complex.__name__ == "complex"
+    assert has_runtimer(complex)
+
+    assert complex(value=2) == 4
+    assert isinstance(timer := runtime(complex), Runtimer)
+    assert 0.01 <= timer.duration < 0.02
+
+    assert complex(value=2, sleep=0.02) == 4
+    assert isinstance(timer := runtime(complex), Runtimer)
+    assert 0.02 <= timer.duration < 0.03
+
+
+def test_runtimer_for_class_method():
+    """Test the runtimer for a class method."""
+
+    class Test(object):
+        @classmethod
+        @runtimer  # Note that the @runtimer decorator *must* go before @classmethod
+        def complex(cls, value: int, sleep: float = 0.01) -> int:
+            time.sleep(sleep)
+            return value * 2
+
+    assert callable(Test.complex)
+    assert Test.complex.__name__ == "complex"
+    assert has_runtimer(Test.complex)
+
+    assert Test.complex(value=2) == 4
+    assert isinstance(timer := runtime(Test.complex), Runtimer)
+    assert 0.01 <= timer.duration < 0.02
+
+    assert Test.complex(value=2, sleep=0.02) == 4
+    assert isinstance(timer := runtime(Test.complex), Runtimer)
+    assert 0.02 <= timer.duration < 0.03
+
+
+def test_runtimer_for_class_instance_method():
+    """Test the runtimer for a class instance method."""
+
+    class Test(object):
+        @runtimer
+        def complex(self, value: int, sleep: float = 0.01) -> int:
+            time.sleep(sleep)
+            return value * 2
+
+    test = Test()
+
+    assert isinstance(test, Test)
+
+    assert callable(test.complex)
+    assert test.complex.__name__ == "complex"
+    assert has_runtimer(test.complex)
+
+    assert test.complex(value=2) == 4
+    assert isinstance(timer := runtime(test.complex), Runtimer)
+    assert 0.01 <= timer.duration < 0.02
+
+    assert test.complex(value=2, sleep=0.02) == 4
+    assert isinstance(timer := runtime(test.complex), Runtimer)
+    assert 0.02 <= timer.duration < 0.03
+
+
+def test_has_runtimer_helper_method():
+    """Test the has_runtimer() helper method."""
+
+    @runtimer
+    def function_with_runtimer():
+        pass
+
+    assert has_runtimer(function_with_runtimer) is True
+
+    def function_without_runtimer():
+        pass
+
+    assert has_runtimer(function_without_runtimer) is False

classicist-1.0.2/source/classicist/version.txt

@@ -1 +0,0 @@
-1.0.2