aspyx 1.0.1__py3-none-any.whl → 1.2.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/reflection.py

@@ -6,6 +6,7 @@ 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
 
@@ -24,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)
@@ -37,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
@@ -55,14 +67,16 @@ class TypeDescriptor:
 
             self.return_type = type_hints.get('return', None)
 
-        def get_decorator(self, decorator) -> Optional[DecoratorDescriptor]:
+        # public
+
+        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 is decorator:
                     return True
@@ -75,15 +89,22 @@ class TypeDescriptor:
     # class properties
 
     _cache = WeakKeyDictionary()
+    _lock = threading.RLock()
 
     # class methods
 
     @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:
-            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
 
@@ -120,14 +141,19 @@ class TypeDescriptor:
 
     # public
 
-    def get_decorator(self, decorator) -> Optional[DecoratorDescriptor]:
+    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
 
         return None
 
-    def has_decorator(self, decorator) -> bool:
+    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
@@ -135,12 +161,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.0.1.dist-info → aspyx-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspyx
-Version: 1.0.1
+Version: 1.2.0
 Summary: A DI and AOP library for Python
 Author-email: Andreas Ernst <andreas.ernst7@gmail.com>
 License: MIT License
@@ -34,8 +34,9 @@ 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)
-![PyPI - Python Version](https://img.shields.io/pypi/pyversions/aspyx)
+![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
 
@@ -56,18 +57,18 @@ Dynamic: license-file
 - [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
@@ -156,7 +157,7 @@ Let's look at the details
 
 `pip install aspyx`
 
-The library is tested with Python version > 3.8
+The library is tested with all Python version > 3.9
 
 Ready to go...
 
@@ -185,8 +186,15 @@ 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 scope which will determine how often instances will be created.
- `singleton` will create it only once - per environment -, while `request` will recreate it on every injection request. The default is `singleton`
+  the name of a - registered - scope which will determine how often instances will be created.
+
+ The following scopes are implemented out of the box:
+ - `singleton`  
+   objects are created once inside an environment and cached. This is the default.
+ - `request`  
+   objects are created on every injection request
+ - `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.
 
@@ -304,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**:
@@ -325,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
 
@@ -445,7 +455,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()
@@ -460,7 +470,7 @@ class TransactionAdvice:
 
 # 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()
@@ -468,11 +478,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
@@ -484,14 +496,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:
+ ```
+
+- `path`  
+  a '.' separated path
+- `type`  
+  the desired type
+- `default`  
+  a default, if no value is registered
 
-Other sources can be added dynamically by just registering them.
+Sources can be added dynamically by registering them.
 
 **Example**:
 ```python
@@ -511,6 +533,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. 
@@ -522,16 +569,24 @@ TypeDescriptor.for_type(<type>)
 ```
 
 it offers the methods
-- `get_methods(local=False)`
-- `get_method(name: str, local=False)`
-- `has_decorator(decorator) -> bool`
-- `get_decorator(decorator)`
+- `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 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
 
 The returned method descriptors offer:
-- `param_types`
-- `return_type`
-- `has_decorator(decorator)`
-- `get_decorator(decorator)`
+- `param_types`  
+   list of arg types
+- `return_type`  
+   the return type
+- `has_decorator(decorator: Callable) -> bool` 
+   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
 
 The management of decorators in turn relies on another utility class `Decorators` that caches decorators.
 
@@ -539,16 +594,29 @@ 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
 ```
 
 
+# Version History
+
+**1.0.1**
+
+- some internal refactorings
+
+**1.1.0**
+
+- added `@on_running()` callback
+- added `thread` scope
+
+**1.2.0**
 
+- added `YamlConfigurationSource`
 
 
       

aspyx-1.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+aspyx/di/__init__.py,sha256=xdb2lsKh00uGMFCWYavhUEMGH15OSeAhUC-iSosqHqU,935
+aspyx/di/di.py,sha256=evfhTznmPNRDjamthSPisMpDhGZJdNmEREUhdJ9nsTE,35571
+aspyx/di/aop/__init__.py,sha256=nOABex49zSyMZ2w1ezwX3Q3yrOcQRSDjDtSj0DwKVbQ,233
+aspyx/di/aop/aop.py,sha256=3GKN6sGlsZbJ7_WSxQvHZNFYouAfU4Eq6H5cBBB_e_4,14455
+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=Xh8g3AuQdgk89nG6GKA4iKILXaqHecD0KqMW2w91hXs,1445
+aspyx/di/configuration/yaml_configuration_source.py,sha256=LM-5J6IRxBBbBAjDeGIFsmiT-61WuGv1sU_zXWNzhkI,549
+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=2oYJKYysH3ULmTzbXdjGBCB1iaLbWh3IPKSnorVLshU,5719
+aspyx-1.2.0.dist-info/licenses/LICENSE,sha256=n4jfx_MNj7cBtPhhI7MCoB_K35cj1icP9yJ4Rh4vlvY,1070
+aspyx-1.2.0.dist-info/METADATA,sha256=wXSu9Clxg4ZZCoiRAhiZzAR1Wcqtjv4NZie4XilJNSs,19009
+aspyx-1.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+aspyx-1.2.0.dist-info/top_level.txt,sha256=A_ZwhBY_ybIgjZlztd44eaOrWqkJAndiqjGlbJ3tR_I,6
+aspyx-1.2.0.dist-info/RECORD,,

aspyx-1.0.1.dist-info/RECORD

@@ -1,14 +0,0 @@
-aspyx/di/__init__.py,sha256=G13Cz1MMElBKNWsrhgTEIvhmIKj5MX4uqK_Apke4w8I,897
-aspyx/di/di.py,sha256=elT3XJokxYxPJ9mx528MAU-pmm9lIZF8_AXKGkjyhBo,31014
-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=dHYoM3jC43QeDVlT6-mGDj05Sz6-Nm91LNE2TfQT1UU,5740
-aspyx/reflection/__init__.py,sha256=r2sNJrfHDpuqaIYu4fTYsoo046gpgn4VTd7bsS3mQJY,282
-aspyx/reflection/proxy.py,sha256=zJ6Psd6zWfFABdrKOf4cULt3gibyqCRdcR6z8WKIkzE,1982
-aspyx/reflection/reflection.py,sha256=NkBK94kjJ7rQpPsK4mzHzX5TLSlWRM3mbNVzkwOZo4o,4379
-aspyx-1.0.1.dist-info/licenses/LICENSE,sha256=n4jfx_MNj7cBtPhhI7MCoB_K35cj1icP9yJ4Rh4vlvY,1070
-aspyx-1.0.1.dist-info/METADATA,sha256=69OakKuzM1UK0YTgH-y6-473YWhylxQvt8v993WsqiU,16798
-aspyx-1.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-aspyx-1.0.1.dist-info/top_level.txt,sha256=A_ZwhBY_ybIgjZlztd44eaOrWqkJAndiqjGlbJ3tR_I,6
-aspyx-1.0.1.dist-info/RECORD,,