aspyx 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

aspyx/di/threading/__init__.py

@@ -0,0 +1,11 @@
+"""
+threading utilities
+"""
+from .synchronized import synchronized, SynchronizeAdvice
+
+imports = [synchronized, SynchronizeAdvice]
+
+__all__ = [
+    "synchronized",
+    "SynchronizeAdvice",
+]

aspyx/di/threading/synchronized.py

@@ -0,0 +1,46 @@
+"""
+Synchronized decorator and advice
+"""
+from __future__ import annotations
+
+import threading
+from weakref import WeakKeyDictionary
+
+from aspyx.reflection import Decorators
+from aspyx.di.aop import advice, around, methods, Invocation
+
+def synchronized():
+    """
+    decorate methods to synchronize them based on an instance related `RLock`
+    """
+    def decorator(func):
+        Decorators.add(func, synchronized)
+        return func #
+
+    return decorator
+
+@advice
+class SynchronizeAdvice():
+    __slots__ = ("locks")
+
+    # constructor
+
+    def __init__(self):
+        self.locks = WeakKeyDictionary()
+
+    # internal
+
+    def get_lock(self, instance) -> threading.RLock:
+        lock = self.locks.get(instance, None)
+        if lock is None:
+            lock = threading.RLock()
+            self.locks[instance] = lock
+
+        return lock
+
+    # around
+
+    @around(methods().decorated_with(synchronized))
+    def synchronize(self, invocation: Invocation):
+        with self.get_lock(invocation.args[0]):
+            return invocation.proceed()

aspyx/reflection/reflection.py

@@ -17,7 +17,7 @@ class DecoratorDescriptor:
         "args"
     ]
 
-    def __init__(self, decorator, *args):
+    def __init__(self, decorator: Callable, *args):
         self.decorator = decorator
         self.args = args
 
@@ -25,6 +25,9 @@ class DecoratorDescriptor:
         return f"@{self.decorator.__name__}({','.join(self.args)})"
 
 class Decorators:
+    """
+    Utility class that caches decorators ( Python does not have a feature for this )
+    """
     @classmethod
     def add(cls, func, decorator, *args):
         decorators = getattr(func, '__decorators__', None)
@@ -38,9 +41,17 @@ class Decorators:
         return getattr(func, '__decorators__', [])
 
 class TypeDescriptor:
+    """
+    This class provides a way to introspect Python classes, their methods, decorators, and type hints.
+    """
     # inner class
 
     class MethodDescriptor:
+        """
+        This class represents a method of a class, including its decorators, parameter types, and return type.
+        """
+        # constructor
+
         def __init__(self, cls, method: Callable):
             self.clazz = cls
             self.method = method
@@ -56,6 +67,11 @@ class TypeDescriptor:
 
             self.return_type = type_hints.get('return', None)
 
+        # public
+
+        def is_async(self) -> bool:
+            return inspect.iscoroutinefunction(self.method)
+
         def get_decorator(self, decorator: Callable) -> Optional[DecoratorDescriptor]:
             for dec in self.decorators:
                 if dec.decorator is decorator:
@@ -82,6 +98,9 @@ class TypeDescriptor:
 
     @classmethod
     def for_type(cls, clazz: Type) -> TypeDescriptor:
+        """
+        Returns a TypeDescriptor for the given class, using a cache to avoid redundant introspection.
+        """
         descriptor = cls._cache.get(clazz)
         if descriptor is None:
             with cls._lock:
@@ -126,6 +145,9 @@ class TypeDescriptor:
     # public
 
     def get_decorator(self, decorator: Callable) -> Optional[DecoratorDescriptor]:
+        """
+        Returns the first decorator of the given type, or None if not found.
+        """
         for dec in self.decorators:
             if dec.decorator is decorator:
                 return dec
@@ -133,6 +155,8 @@ class TypeDescriptor:
         return None
 
     def has_decorator(self, decorator: Callable) -> bool:
+        """
+        Checks if the class has a decorator of the given type."""
         for dec in self.decorators:
             if dec.decorator is decorator:
                 return True
@@ -140,12 +164,20 @@ class TypeDescriptor:
         return False
 
     def get_methods(self, local = False) ->  list[TypeDescriptor.MethodDescriptor]:
+        """
+        Returns a list of MethodDescriptor objects for the class.
+        If local is True, only returns methods defined in the class itself, otherwise includes inherited methods.
+        """
         if local:
             return list(self.local_methods.values())
         else:
             return list(self.methods.values())
 
     def get_method(self, name: str, local = False) -> Optional[TypeDescriptor.MethodDescriptor]:
+        """
+        Returns a MethodDescriptor for the method with the given name.
+        If local is True, only searches for methods defined in the class itself, otherwise includes inherited methods.
+        """
         if local:
             return self.local_methods.get(name, None)
         else:

{aspyx-1.1.0.dist-info → aspyx-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspyx
-Version: 1.1.0
+Version: 1.3.0
 Summary: A DI and AOP library for Python
 Author-email: Andreas Ernst <andreas.ernst7@gmail.com>
 License: MIT License
@@ -37,15 +37,18 @@ Dynamic: license-file
 ![Python Versions](https://img.shields.io/badge/python-3.9%20|%203.10%20|%203.11%20|%203.12-blue)
 ![License](https://img.shields.io/github/license/coolsamson7/aspyx)
 ![coverage](https://img.shields.io/badge/coverage-94%25-brightgreen)
+[![PyPI](https://img.shields.io/pypi/v/aspyx)](https://pypi.org/project/aspyx/)
 
 ## Table of Contents
 
-- [Introduction](#aspyx)
+- [Motivation](#motivation)
+- [Introduction](#introduction)
 - [Installation](#installation)
 - [Registration](#registration)
   - [Class](#class)
   - [Class Factory](#class-factory)
   - [Method](#method)
+  - [Conditional](#conditional)
 - [Environment](#environment)
   - [Definition](#definition)
   - [Retrieval](#retrieval)
@@ -59,22 +62,38 @@ Dynamic: license-file
 - [Reflection](#reflection)
 - [Version History](#version-history)
 
+# Motivation
+
+While working on some AI related topics in Python, i required a simple DI framework. 
+Looking at the existing solutions - there are quite a number of - i was not quite happy. Either the solutions 
+lacked functionality - starting with that usually aop and di are separate libraries -, that i am accustomed to from other languages, or the API was in my mind too clumsy and "technical".
+
+So, why not develop one on my own...Having done that in other languages previously, the task was not that hard, and last but not least...it is fun :-) 
+
 # Introduction
 
 Aspyx is a small python libary, that adds support for both dependency injection and aop.
 
-The following features are supported 
+The following di features are supported 
 - constructor and setter injection
+- possibility to define custom injections
 - post processors
-- factory classes and methods
+- support for factory classes and methods
 - support for eager construction
-- support for singleton and request scopes
+- support for scopes singleton, request and thread
 - possibilty to add custom scopes
-- lifecycle events methods
-- bundling of injectable object sets by environment classes including recursive imports and inheritance
-- container instances that relate to environment classes and manage the lifecylce of related objects
+- conditional registration of classes and factories 
+- lifecycle events methods `on_init`, `on_destroy`
+- bundling of injectable objects according to their module location including recursive imports and inheritance
+- instatiation of - possibly multiple - container instances - so called environments -  that manage the lifecylce of related objects
+- filtering of classes by associating "features" sets to environment ( similar to spring profiles )
 - hierarchical environments
 
+With respect to aop:
+- support for before, around, after and error aspects 
+- sync and async method support
+- `synchronized` decorator that adds locking to methods
+
 The library is thread-safe!
 
 Let's look at a simple example
@@ -155,11 +174,11 @@ Let's look at the details
 
 # Installation
 
-`pip install aspyx`
+Just install from PyPI with 
 
-The library is tested with all Python version > 3.9
+`pip install aspyx`
 
-Ready to go...
+The library is tested with all Python version >= 3.9
 
 # Registration
 
@@ -192,9 +211,9 @@ The decorator accepts the keyword arguments
  - `singleton`  
    objects are created once inside an environment and cached. This is the default.
  - `request`  
-   obejcts are created on every injection request
+   objects are created on every injection request
  - `thread`  
-   objects are cerated and cached with respect to the current thread.
+   objects are created and cached with respect to the current thread.
 
  Other scopes - e.g. session related scopes - can be defined dynamically. Please check the corresponding chapter.
 
@@ -233,6 +252,22 @@ class Foo:
 
  The same arguments as in `@injectable` are possible.
 
+## Conditional
+
+All `@injectable` declarations can be supplemented with 
+
+```python
+@conditional(<condition>, ..., <condition>)
+```
+
+decorators that act as filters in the context of an environment.
+
+Valid conditions are created by:
+- `requires_class(clazz: Type)`  
+  the injectable is valid, if the specified class is registered as well.
+- `requires_feature(feature: str)`  
+  the injectable is valid, if the environment defines the specified feature.
+
 # Environment
 
 ## Definition
@@ -251,6 +286,26 @@ environment = Environment(SampleEnvironment)
 
 The default is that all eligible classes, that are implemented in the containing module or in any submodule will be managed.
 
+By adding the parameter `features: list[str]`, it is possible to filter injectables by evaluating the corresponding `@conditional` decorators.
+
+**Example**: 
+```python
+
+@injectable()
+@conditional(requires_feature("dev"))
+class DevOnly:
+     def __init__(self):
+        pass
+
+@environment()
+class SampleEnvironmen()):
+    def __init__(self):
+        pass
+
+environment = Environment(SampleEnvironment, features=["dev"])
+```
+
+
 By adding an `imports: list[Type]` parameter, specifying other environment types, it will register the appropriate classes recursively.
 
 **Example**: 
@@ -428,18 +483,35 @@ Different aspects - with the appropriate decorator - are possible:
 - `before`  
    methods that will be executed _prior_ to the original method
 - `around`  
-   methods that will be executed _around_ to the original method giving it the possibility add side effects or even change the parameters.
+   methods that will be executed _around_ to the original method giving it the possibility to add side effects or even change the parameters.
 - `after`  
-    methods that will be executed _after_ to the original method
+   methods that will be executed _after_ to the original method
 - `error`  
-   methods that will be executed in case of a caught exception, which can be retrieved by `invocation.exception`
+   methods that will be executed in case of a caught exception
+
+All methods are expected to have single `Invocation` parameter, that stores
 
-All methods are expected to hava single `Invocation` parameter, that stores, the function, args and kwargs, the return value and possible exceptions.
+- `func` the target function
+- `args` the suppliued args
+- `kwargs` the keywords args
+- `result` the result ( initially `None`)
+- `exception` a possible caught excpetion ( initially `None`)
 
 It is essential for `around` methods to call `proceed()` on the invocation, which will call the next around method in the chain and finally the original method.
 If the `proceed` is called with parameters, they will replace the original parameters! 
 
-The argument list to the corresponding decorators control, how aspects are associated with which methods.
+**Example**: Parameter modifications
+
+```python
+@around(methods().named("say"))
+def call_around(self, invocation: Invocation):
+    args = [invocation.args[0],invocation.args[1] + "!"] # 0 is self!
+
+    return invocation.proceed(*args)
+```
+
+The argument list to the corresponding decorators control which methods are targeted by the advice.
+
 A fluent interface is used describe the mapping. 
 The parameters restrict either methods or classes and are constructed by a call to either `methods()` or `classes()`.
 
@@ -448,6 +520,8 @@ Both add the fluent methods:
    defines the matching classes
 - `named(name: str)`  
    defines method or class names
+- `that_are_async()`  
+   defines async methods
 - `matches(re: str)`  
    defines regular expressions for methods or classes
 - `decorated_with(type: Type)`  
@@ -455,7 +529,7 @@ Both add the fluent methods:
 
 The fluent methods `named`, `matches` and `of_type` can be called multiple times!
 
-**Example**:
+**Example**: react on both `transactional` decorators on methods or classes
 
 ```python
 @injectable()
@@ -468,6 +542,10 @@ class TransactionAdvice:
         ...
 ```
 
+With respect to async methods, you need to make sure, to replace a `proceeed()` with a `await proceed_async()` to have the overall chain async!
+
+A handy decorator `@synchronized` is implemented that automatically synchronizes methods with a `RLock` associated with the instance.
+
 # Configuration 
 
 It is possible to inject configuration values, by decorating methods with `@inject-value(<name>)` given a configuration key.
@@ -478,11 +556,13 @@ class Foo:
     def __init__(self):
         pass
 
-    @value("OS")
-    def inject_value(self, os: str):
+    @inject_value("HOME")
+    def inject_home(self, os: str):
         ...
 ```
 
+If required a coercion will be executed.
+
 This concept relies on a central object `ConfigurationManager` that stores the overall configuration values as provided by so called configuration sources that are defined as follows.
 
 ```python
@@ -494,14 +574,24 @@ class ConfigurationSource(ABC):
 
     @abstractmethod
     def load(self) -> dict:
-        pass
 ```
 
 The `load` method is able to return a tree-like structure by returning a `dict`.
 
-As a default environment variables are already supported.
+Configuration variables are retrieved with the method
+
+```python
+def get(self, path: str, type: Type[T], default : Optional[T]=None) -> T:
+ ```
 
-Other sources can be added dynamically by just registering them.
+- `path`  
+  a '.' separated path
+- `type`  
+  the desired type
+- `default`  
+  a default, if no value is registered
+
+Sources can be added dynamically by registering them.
 
 **Example**:
 ```python
@@ -521,6 +611,31 @@ class SampleConfigurationSource(ConfigurationSource):
             }
 ```
 
+Two specific source are already implemented:
+- `EnvConfigurationSource`  
+   reads the os environment variables
+- `YamlConfigurationSource`  
+   reads a specific yaml file
+
+Typically you create the required configuration sources in an environment class, e.g.
+
+```python
+@environment()
+class SampleEnvironment:
+    # constructor
+
+    def __init__(self):
+        pass
+
+    @create()
+    def create_env_source(self) -> EnvConfigurationSource:
+        return EnvConfigurationSource()
+
+    @create()
+    def create_yaml_source(self) -> YamlConfigurationSource:
+        return YamlConfigurationSource("config.yaml")
+```
+
 # Reflection
 
 As the library heavily relies on type introspection of classes and methods, a utility class `TypeDescriptor` is available that covers type information on classes. 
@@ -537,7 +652,7 @@ it offers the methods
 - `get_method(name: str, local=False)`  
    return a single either local or overall method
 - `has_decorator(decorator: Callable) -> bool`  
-   return `True`, if the class is decorated with the specified decrator
+   return `True`, if the class is decorated with the specified decorator
 - `get_decorator(decorator) -> Optional[DecoratorDescriptor]`  
    return a descriptor covering the decorator. In addition to the callable, it also stores the supplied args in the `args` property
 
@@ -545,9 +660,9 @@ The returned method descriptors offer:
 - `param_types`  
    list of arg types
 - `return_type`  
-   the retur type
+   the return type
 - `has_decorator(decorator: Callable) -> bool` 
-   return `True`, if the method is decorated with the specified decrator
+   return `True`, if the method is decorated with the specified decorator
 - `get_decorator(decorator: Callable) -> Optional[DecoratorDescriptor]`  
    return a descriptor covering the decorator. In addition to the callable, it also stores the supplied args in the `args` property
 
@@ -557,9 +672,9 @@ Whenver you define a custom decorator, you will need to register it accordingly.
 
 **Example**:
 ```python
-def transactional():
+def transactional(scope):
     def decorator(func):
-        Decorators.add(func, transactional)
+        Decorators.add(func, transactional, scope) # also add _all_ parameters in order to cache them
         return func
 
     return decorator
@@ -577,6 +692,12 @@ def transactional():
 - added `@on_running()` callback
 - added `thread` scope
 
+**1.2.0**
+
+- added `YamlConfigurationSource`
+
+**1.2.1**
+
 
       
 

aspyx-1.3.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+aspyx/di/__init__.py,sha256=OfETLGaquTbFHhhDRzzGtnSu-KkMj68aDdEaVU19KoI,1107
+aspyx/di/di.py,sha256=OmvcEd2Arsyo0n9Vh40LM_-jLFdOg-bKwahcEINJ7GA,38363
+aspyx/di/aop/__init__.py,sha256=nOABex49zSyMZ2w1ezwX3Q3yrOcQRSDjDtSj0DwKVbQ,233
+aspyx/di/aop/aop.py,sha256=GPkNE6CgQZUPeMlDdmE5TiksNLSgPb2A8D2IXRZmJ_M,16887
+aspyx/di/configuration/__init__.py,sha256=mweJ3tZX1YJfY1d4ra-i0TWEcF3EwXBpGbHrKg1Kc6E,380
+aspyx/di/configuration/configuration.py,sha256=KfPjrlUhhmEOUxdJiXePt5RGxKc8JczkWqlEBjpWQTg,4362
+aspyx/di/configuration/env_configuration_source.py,sha256=FXPvREzq2ZER6_GG5xdpx154TQQDxZVf7LW7cvaylAk,1446
+aspyx/di/configuration/yaml_configuration_source.py,sha256=NDl3SeoLMNVlzHgfP-Ysvhco1tRew_zFnBL5gGy2WRk,550
+aspyx/di/threading/__init__.py,sha256=qrWdaq7MewQ2UmZy4J0Dn6BhY-ahfiG3xsv-EHqoqSE,191
+aspyx/di/threading/synchronized.py,sha256=awFm8T5_lPw0An-H4-jdTUumPmX348WiYw1x8xyz4qs,1053
+aspyx/di/util/__init__.py,sha256=8H2yKkXu3nkRGeTerb8ialzKGfvzUx44XUWFUYcYuQM,125
+aspyx/di/util/stringbuilder.py,sha256=JywkLxZfaQUUWjSB5wvqA6a6Cfs3sW1jbaZ1z4U0-CQ,540
+aspyx/reflection/__init__.py,sha256=r2sNJrfHDpuqaIYu4fTYsoo046gpgn4VTd7bsS3mQJY,282
+aspyx/reflection/proxy.py,sha256=zJ6Psd6zWfFABdrKOf4cULt3gibyqCRdcR6z8WKIkzE,1982
+aspyx/reflection/reflection.py,sha256=0kQXQcyOCj29vy5Ls4dbAlvOKsY7FRyHndiygZzg7HY,5826
+aspyx-1.3.0.dist-info/licenses/LICENSE,sha256=n4jfx_MNj7cBtPhhI7MCoB_K35cj1icP9yJ4Rh4vlvY,1070
+aspyx-1.3.0.dist-info/METADATA,sha256=lxqBe-dsW1oe6HgBOfoRIUk_q-qFObZSNpO4e8Xi40U,21691
+aspyx-1.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+aspyx-1.3.0.dist-info/top_level.txt,sha256=A_ZwhBY_ybIgjZlztd44eaOrWqkJAndiqjGlbJ3tR_I,6
+aspyx-1.3.0.dist-info/RECORD,,

aspyx-1.1.0.dist-info/RECORD

@@ -1,16 +0,0 @@
-aspyx/di/__init__.py,sha256=U2-4JnCmSO_IXCnN1jeig9nuWfJN__z9yRzl1WexQJk,927
-aspyx/di/di.py,sha256=VVLOXhTKJer2cV0rNEOqMLyMigsNMEQ7xoc-6M7a8wU,34296
-aspyx/di/aop/__init__.py,sha256=nOABex49zSyMZ2w1ezwX3Q3yrOcQRSDjDtSj0DwKVbQ,233
-aspyx/di/aop/aop.py,sha256=1RUgijk8RsiXWTizfNQX1IfHF7b96kCPdUgahX_J4Io,14457
-aspyx/di/configuration/__init__.py,sha256=Zw7h-OlbJD7LyJvzkgyF0EmVqra6oN_Pt0HuUdjTPTA,249
-aspyx/di/configuration/configuration.py,sha256=jJJSHRG2wOIvle23Xc8CQ4WM7lp_xCL8-ENVZO603uQ,5682
-aspyx/di/util/__init__.py,sha256=8H2yKkXu3nkRGeTerb8ialzKGfvzUx44XUWFUYcYuQM,125
-aspyx/di/util/stringbuilder.py,sha256=JywkLxZfaQUUWjSB5wvqA6a6Cfs3sW1jbaZ1z4U0-CQ,540
-aspyx/reflection/__init__.py,sha256=r2sNJrfHDpuqaIYu4fTYsoo046gpgn4VTd7bsS3mQJY,282
-aspyx/reflection/proxy.py,sha256=zJ6Psd6zWfFABdrKOf4cULt3gibyqCRdcR6z8WKIkzE,1982
-aspyx/reflection/reflection.py,sha256=HfPFd_FehTGmgF6NA-IJ_aHePE6GXM1ag7K3h8YIXjI,4600
-aspyx-1.1.0.dist-info/licenses/LICENSE,sha256=n4jfx_MNj7cBtPhhI7MCoB_K35cj1icP9yJ4Rh4vlvY,1070
-aspyx-1.1.0.dist-info/METADATA,sha256=rdeICMYyQSJmSZDJZrsdw6l5ZVrQrxvAPS_z47ObM-Y,17989
-aspyx-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-aspyx-1.1.0.dist-info/top_level.txt,sha256=A_ZwhBY_ybIgjZlztd44eaOrWqkJAndiqjGlbJ3tR_I,6
-aspyx-1.1.0.dist-info/RECORD,,