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

aspyx/di/util/__init__.py

@@ -0,0 +1,8 @@
+"""
+This module provides utility functions.
+"""
+from .stringbuilder import StringBuilder
+
+__all__ = [
+    "StringBuilder",
+]

aspyx/di/util/stringbuilder.py

@@ -0,0 +1,31 @@
+"""
+Utility class for Java lovers
+"""
+class StringBuilder:
+    ___slots__ = ("_parts",)
+
+    # constructor
+
+    def __init__(self):
+        self._parts = []
+
+    # public
+
+    def append(self, s: str) -> "StringBuilder":
+        self._parts.append(str(s))
+
+        return self
+
+    def extend(self, iterable) -> "StringBuilder":
+        for s in iterable:
+            self._parts.append(str(s))
+
+        return self
+
+    def clear(self):
+        self._parts.clear()
+
+    # object
+
+    def __str__(self):
+        return ''.join(self._parts)

aspyx/reflection/__init__.py

@@ -1,3 +1,6 @@
+"""
+This module provides tools for dynamic proxy creation and reflection
+"""
 from .proxy import DynamicProxy
 from .reflection import Decorators, TypeDescriptor, DecoratorDescriptor
 
@@ -6,4 +9,4 @@ __all__ = [
     "Decorators",
     "DecoratorDescriptor",
     "TypeDescriptor"
-]
+]

aspyx/reflection/proxy.py

@@ -1,3 +1,6 @@
+"""
+Dynamic proxies for method interception and delegation.
+"""
 from typing import Generic, TypeVar, Type
 
 T = TypeVar("T")
@@ -22,7 +25,7 @@ class DynamicProxy(Generic[T]):
 
     Attributes:
         type: The proxied class type.
-        invocationHandler: The handler that processes intercepted method calls.
+        invocation_handler: The handler that processes intercepted method calls.
     """
     # inner class
 
@@ -40,19 +43,19 @@ class DynamicProxy(Generic[T]):
     # class methods
 
     @classmethod
-    def create(cls, type: Type[T], invocationHandler: 'DynamicProxy.InvocationHandler') -> T:
-        return DynamicProxy(type, invocationHandler)
+    def create(cls, type: Type[T], invocation_handler: 'DynamicProxy.InvocationHandler') -> T:
+        return DynamicProxy(type, invocation_handler)
 
     # constructor
 
-    def __init__(self, type: Type[T], invocationHandler: 'DynamicProxy.InvocationHandler'):
+    def __init__(self, type: Type[T], invocation_handler: 'DynamicProxy.InvocationHandler'):
         self.type = type
-        self.invocationHandler = invocationHandler
+        self.invocation_handler = invocation_handler
 
     # public
 
     def __getattr__(self, name):
         def wrapper(*args, **kwargs):
-            return self.invocationHandler.invoke(DynamicProxy.Invocation(self.type, name, *args, **kwargs))
+            return self.invocation_handler.invoke(DynamicProxy.Invocation(self.type, name, *args, **kwargs))
 
-        return wrapper
+        return wrapper

aspyx/reflection/reflection.py

@@ -1,10 +1,16 @@
+"""
+This module provides a TypeDescriptor class that allows introspection of Python classes,
+including their methods, decorators, and type hints. It supports caching for performance
+"""
 from __future__ import annotations
 
 import inspect
 from inspect import signature, getmembers
+import threading
 from typing import Callable, get_type_hints, Type, Dict, Optional
 from weakref import WeakKeyDictionary
 
+
 class DecoratorDescriptor:
     __slots__ = [
         "decorator",
@@ -39,25 +45,25 @@ class TypeDescriptor:
             self.clazz = cls
             self.method = method
             self.decorators: list[DecoratorDescriptor] = Decorators.get(method)
-            self.paramTypes : list[Type] = []
+            self.param_types : list[Type] = []
 
             type_hints = get_type_hints(method)
             sig = signature(method)
 
-            for name, param in sig.parameters.items():
+            for name, _ in sig.parameters.items():
                 if name != 'self':
-                    self.paramTypes.append(type_hints.get(name, object))
+                    self.param_types.append(type_hints.get(name, object))
 
-            self.returnType = type_hints.get('return', None)
+            self.return_type = type_hints.get('return', None)
 
-        def get_decorator(self, decorator):
+        def get_decorator(self, decorator: Callable) -> Optional[DecoratorDescriptor]:
             for dec in self.decorators:
                 if dec.decorator is decorator:
                     return dec
 
             return None
 
-        def has_decorator(self, decorator):
+        def has_decorator(self, decorator: Callable) -> bool:
             for dec in self.decorators:
                 if dec.decorator is decorator:
                     return True
@@ -67,11 +73,10 @@ class TypeDescriptor:
         def __str__(self):
             return f"Method({self.method.__name__})"
 
-    # class methods
-
     # class properties
 
     _cache = WeakKeyDictionary()
+    _lock = threading.RLock()
 
     # class methods
 
@@ -79,8 +84,12 @@ class TypeDescriptor:
     def for_type(cls, clazz: Type) -> TypeDescriptor:
         descriptor = cls._cache.get(clazz)
         if descriptor is None:
-            descriptor = TypeDescriptor(clazz)
-            cls._cache[clazz] = descriptor
+            with cls._lock:
+                descriptor = cls._cache.get(clazz)
+                if descriptor is None:
+                    descriptor = TypeDescriptor(clazz)
+                    cls._cache[clazz] = descriptor
+
         return descriptor
 
     # constructor
@@ -88,27 +97,25 @@ class TypeDescriptor:
     def __init__(self, cls):
         self.cls = cls
         self.decorators = Decorators.get(cls)
-        self.methods: Dict[str, TypeDescriptor.MethodDescriptor] = dict()
-        self.localMethods: Dict[str, TypeDescriptor.MethodDescriptor] = dict()
+        self.methods: Dict[str, TypeDescriptor.MethodDescriptor] = {}
+        self.local_methods: Dict[str, TypeDescriptor.MethodDescriptor] = {}
 
         # check superclasses
 
-        self.superTypes = [TypeDescriptor.for_type(x) for x in cls.__bases__ if not x is object]
+        self.super_types = [TypeDescriptor.for_type(x) for x in cls.__bases__ if not x is object]
 
-        for superType in self.superTypes:
-            self.methods = self.methods | superType.methods
+        for super_type in self.super_types:
+            self.methods = self.methods | super_type.methods
 
         # methods
 
         for name, member in self._get_local_members(cls):
             method = TypeDescriptor.MethodDescriptor(cls, member)
-            self.localMethods[name] = method
+            self.local_methods[name] = method
             self.methods[name] = method
 
     # internal
 
-    #isinstance(attr, classmethod)
-
     def _get_local_members(self, cls):
         return [
             (name, value)
@@ -118,22 +125,28 @@ class TypeDescriptor:
 
     # public
 
-    def get_decorator(self, decorator) -> Optional[DecoratorDescriptor]:
+    def get_decorator(self, decorator: Callable) -> Optional[DecoratorDescriptor]:
         for dec in self.decorators:
             if dec.decorator is decorator:
                 return dec
 
         return None
 
-    def has_decorator(self, decorator) -> bool:
+    def has_decorator(self, decorator: Callable) -> bool:
         for dec in self.decorators:
-            if dec.decorator.__name__ == decorator.__name__:
+            if dec.decorator is decorator:
                 return True
 
         return False
 
-    def get_local_method(self, name) -> Optional[MethodDescriptor]:
-        return self.localMethods.get(name, None)
+    def get_methods(self, local = False) ->  list[TypeDescriptor.MethodDescriptor]:
+        if local:
+            return list(self.local_methods.values())
+        else:
+            return list(self.methods.values())
 
-    def get_method(self, name) -> Optional[MethodDescriptor]:
-        return self.methods.get(name, None)
+    def get_method(self, name: str, local = False) -> Optional[TypeDescriptor.MethodDescriptor]:
+        if local:
+            return self.local_methods.get(name, None)
+        else:
+            return self.methods.get(name, None)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspyx
-Version: 1.0.0
+Version: 1.1.0
 Summary: A DI and AOP library for Python
 Author-email: Andreas Ernst <andreas.ernst7@gmail.com>
 License: MIT License
@@ -25,7 +25,7 @@ License: MIT License
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Dynamic: license-file
@@ -34,11 +34,14 @@ Dynamic: license-file
 
 ![Pylint](https://github.com/coolsamson7/aspyx/actions/workflows/pylint.yml/badge.svg)
 ![Build Status](https://github.com/coolsamson7/aspyx/actions/workflows/ci.yml/badge.svg)
-
+![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)
 
 ## Table of Contents
 
 - [Introduction](#aspyx)
+- [Installation](#installation)
 - [Registration](#registration)
   - [Class](#class)
   - [Class Factory](#class-factory)
@@ -53,30 +56,32 @@ Dynamic: license-file
 - [Custom scopes](#custom-scopes)
 - [AOP](#aop)
 - [Configuration](#configuration)
+- [Reflection](#reflection)
+- [Version History](#version-history)
 
 # Introduction
 
 Aspyx is a small python libary, that adds support for both dependency injection and aop.
 
 The following features are supported 
-- constructor injection
-- method injection
+- constructor and setter injection
 - post processors
 - factory classes and methods
 - support for eager construction
-- support for singleton and reuqest scopes
+- support for singleton and request scopes
 - 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
 - hierarchical environments
 
+The library is thread-safe!
+
 Let's look at a simple example
 
 ```python
 from aspyx.di import injectable, on_init, on_destroy, environment, Environment
 
-
 @injectable()
 class Foo:
     def __init__(self):
@@ -85,13 +90,12 @@ class Foo:
     def hello(msg: str):
         print(f"hello {msg}")
 
-
 @injectable()  # eager and singleton by default
 class Bar:
     def __init__(self, foo: Foo): # will inject the Foo dependency
         self.foo = foo
 
-    @on_init() # a lifecycle callback called  after the constructor
+    @on_init() # a lifecycle callback called after the constructor and all possible injections
     def init(self):
         ...
 
@@ -101,41 +105,40 @@ class Bar:
 
 @environment()
 class SampleEnvironment:
-    # constructor
-
     def __init__(self):
         pass
 
-
 # go, forrest
 
-environment = SampleEnvironment(Configuration)
+environment = Environment(SampleEnvironment)
 
 bar = env.get(Bar)
-bar.foo.hello("Andi")
+
+bar.foo.hello("world")
 ```
 
-The concepts should be pretty familiar , as well as the names which are a combination of Spring and Angular names :-)
+The concepts should be pretty familiar as well as the names which are a combination of Spring and Angular names :-)
 
 Let's add some aspects...
 
 ```python
+
 @advice
 class SampleAdvice:
-    def __init__(self):
+    def __init__(self): # could inject additional stuff
         pass
 
     @before(methods().named("hello").of_type(Foo))
-    def callBefore(self, invocation: Invocation):
+    def call_before(self, invocation: Invocation):
         print("before Foo.hello(...)")
 
     @error(methods().named("hello").of_type(Foo))
-    def callError(self, invocation: Invocation):
+    def call_error(self, invocation: Invocation):
         print("error Foo.hello(...)")
         print(invocation.exception)
 
     @around(methods().named("hello"))
-    def callAround(self, invocation: Invocation):
+    def call_around(self, invocation: Invocation):
         print("around Foo.hello()")
 
         return invocation.proceed()
@@ -150,6 +153,14 @@ The invocation parameter stores the complete context of the current execution, w
 
 Let's look at the details
 
+# Installation
+
+`pip install aspyx`
+
+The library is tested with all Python version > 3.9
+
+Ready to go...
+
 # Registration
 
 Different mechanisms are available that make classes eligible for injection
@@ -171,12 +182,21 @@ All referenced types will be injected by the environemnt.
 
 Only eligible types are allowed, of course!
 
+The decorator accepts the keyword arguments
+- `eager : boolean`  
+  if `True`, the container will create the instances automatically while booting the environment. This is the default.
+- `scope: str`  
+  the name of a - registered - scope which will determine how often instances will be created.
 
- The decorator accepts the keyword arguments
- - `eager=True` if `True`, the container will create the instances automatically while booting the environment
- - `scope="singleton"` defines how often instances will be created. `singleton` will create it only once - per environment -, while `request` will recreate it on every injection request
+ The following scopes are implemented out of the box:
+ - `singleton`  
+   objects are created once inside an environment and cached. This is the default.
+ - `request`  
+   obejcts are created on every injection request
+ - `thread`  
+   objects are cerated and cached with respect to the current thread.
 
- Other scopes can be defined. Please check the corresponding chapter.
+ Other scopes - e.g. session related scopes - can be defined dynamically. Please check the corresponding chapter.
 
 ## Class Factory
 
@@ -292,7 +312,7 @@ Different decorators are implemented, that call methods with computed values
    the method is called with all resolved parameter types ( same as the constructor call)
 - `@inject_environment`  
    the method is called with the creating environment as a single parameter
-- `@value()`  
+- `@inject_value()`  
    the method is called with a resolved configuration value. Check the corresponding chapter
 
 **Example**:
@@ -313,9 +333,11 @@ class Foo:
 
 ## Lifecycle methods
 
-It is possible to mark specific lifecle methods. 
+It is possible to mark specific lifecyle methods. 
 - `@on_init()` 
    called after the constructor and all other injections.
+- `@on_running()` 
+   called an environment has initialized all eager objects.
 - `@on_destroy()` 
    called during shutdown of the environment
 
@@ -386,17 +408,17 @@ class SampleAdvice:
         pass
 
     @before(methods().named("hello").of_type(Foo))
-    def callBefore(self, invocation: Invocation):
+    def call_before(self, invocation: Invocation):
         # arguments: invocation.args
         print("before Foo.hello(...)")
 
     @error(methods().named("hello").of_type(Foo))
-    def callError(self, invocation: Invocation):
+    def call_error(self, invocation: Invocation):
         print("error Foo.hello(...)")
         print(invocation.exception)
 
     @around(methods().named("hello"))
-    def callAround(self, invocation: Invocation):
+    def call_around(self, invocation: Invocation):
         print("around Foo.hello()")
 
         return invocation.proceed()  # will leave a result in invocation.result or invocation.exception in case of an exception
@@ -417,7 +439,7 @@ All methods are expected to hava single `Invocation` parameter, that stores, the
 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 arguments to the corresponding decorators control, how aspects are associated with which methods.
+The argument list to the corresponding decorators control, how aspects are associated with which methods.
 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()`.
 
@@ -431,11 +453,24 @@ Both add the fluent methods:
 - `decorated_with(type: Type)`  
    defines decorators on methods or classes
 
-The fluent methods `named`, `matches` and `of_type` can be called multiple timess!
+The fluent methods `named`, `matches` and `of_type` can be called multiple times!
+
+**Example**:
+
+```python
+@injectable()
+class TransactionAdvice:
+    def __init__(self):
+        pass
+
+    @around(methods().decorated_with(transactional), classes().decorated_with(transactional))
+    def establish_transaction(self, invocation: Invocation):
+        ...
+```
 
 # Configuration 
 
-It is possible to inject configuration values, by decorating methods with `@value(<name>)` given a configuration key.
+It is possible to inject configuration values, by decorating methods with `@inject-value(<name>)` given a configuration key.
 
 ```python
 @injectable()
@@ -452,10 +487,11 @@ This concept relies on a central object `ConfigurationManager` that stores the o
 
 ```python
 class ConfigurationSource(ABC):
-    def __init__(self, manager: ConfigurationManager):
-        manager._register(self)
+    def __init__(self):
         pass
 
+   ...
+
     @abstractmethod
     def load(self) -> dict:
         pass
@@ -467,14 +503,12 @@ As a default environment variables are already supported.
 
 Other sources can be added dynamically by just registering them.
 
+**Example**:
 ```python
 @injectable()
 class SampleConfigurationSource(ConfigurationSource):
-    # constructor
-
-    def __init__(self, manager: ConfigurationManager):
-        super().__init__(manager)
-
+    def __init__(self):
+        super().__init__()
 
     def load(self) -> dict:
         return {
@@ -487,7 +521,61 @@ class SampleConfigurationSource(ConfigurationSource):
             }
 ```
 
+# 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. 
+
+After beeing instatiated with
+
+```python
+TypeDescriptor.for_type(<type>)
+```
+
+it offers the methods
+- `get_methods(local=False)`  
+   return a list of either local or overall 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
+- `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
+
+The returned method descriptors offer:
+- `param_types`  
+   list of arg types
+- `return_type`  
+   the retur type
+- `has_decorator(decorator: Callable) -> bool` 
+   return `True`, if the method is decorated with the specified decrator
+- `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
+
+The management of decorators in turn relies on another utility class `Decorators` that caches decorators.
+
+Whenver you define a custom decorator, you will need to register it accordingly.
+
+**Example**:
+```python
+def transactional():
+    def decorator(func):
+        Decorators.add(func, transactional)
+        return func
+
+    return decorator
+```
+
+
+# Version History
+
+**1.0.1**
+
+- some internal refactorings
+
+**1.1.0**
 
+- added `@on_running()` callback
+- added `thread` scope
 
 
       

aspyx-1.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+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,,

aspyx-1.0.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-aspyx/di/__init__.py,sha256=US6i6s94TIpk4eiRFKYm9JB0NnU9F_3RAoIoXa-OnTI,800
-aspyx/di/di.py,sha256=IdMNkPmMaVhRNr8heE8msGO3KYEc69pf2pjcJ8_rp4E,31169
-aspyx/di/aop/__init__.py,sha256=2mv6o38HHoBzF_nx8rsrvuOlUlNgYITmNRcQJVT2Bk8,213
-aspyx/di/aop/aop.py,sha256=stgSLSBpOd9XV_qo7KEazinq8Ul_csWbCx1w30dioWw,14647
-aspyx/di/configuration/__init__.py,sha256=YgUk1bHVYq1EJ9W4D_CJ9ZM-3kje-vzPNMxBdUm0Vlg,211
-aspyx/di/configuration/configuration.py,sha256=6EG2kf2v5pk9fTeCQUD5j6Jo5v00CFd5Nz7qXyYmxKw,5725
-aspyx/reflection/__init__.py,sha256=jZAjw5NDrtXENmlBsQ0u9MobcNkfEuT0Oey8IWNYh34,204
-aspyx/reflection/proxy.py,sha256=Re643BJAgbQjmDXO5JAvj4mu3RTpe_HF3TcFQ1euArg,1910
-aspyx/reflection/reflection.py,sha256=LIUu-SxA_GJ1JurbQKTrvMUrE05OOcXxXOu65zRWubw,4004
-aspyx-1.0.0.dist-info/licenses/LICENSE,sha256=n4jfx_MNj7cBtPhhI7MCoB_K35cj1icP9yJ4Rh4vlvY,1070
-aspyx-1.0.0.dist-info/METADATA,sha256=3AuH9LBUHpPfxu9BcmawTaaJIHTBWwHuFpP_gBasyh0,15227
-aspyx-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-aspyx-1.0.0.dist-info/top_level.txt,sha256=A_ZwhBY_ybIgjZlztd44eaOrWqkJAndiqjGlbJ3tR_I,6
-aspyx-1.0.0.dist-info/RECORD,,