aspyx-service 0.9.0__tar.gz → 0.10.0__tar.gz

{aspyx_service-0.9.0 → aspyx_service-0.10.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: aspyx_service
-Version: 0.9.0
-Summary: Service framework on top of aspyx
+Version: 0.10.0
+Summary: Aspyx Service framework
 Author-email: Andreas Ernst <andreas.ernst7@gmail.com>
 License: MIT License
         
@@ -26,11 +26,12 @@ License: MIT License
         SOFTWARE.
 License-File: LICENSE
 Requires-Python: >=3.9
-Requires-Dist: aspyx>=1.4.1
+Requires-Dist: aspyx>=1.5.0
 Requires-Dist: fastapi~=0.115.13
 Requires-Dist: httpx~=0.28.1
 Requires-Dist: msgpack~=1.1.1
 Requires-Dist: python-consul2~=0.1.5
+Requires-Dist: uvicorn[standard]
 Description-Content-Type: text/markdown
 
 aspyx-service

{aspyx_service-0.9.0 → aspyx_service-0.10.0}/pyproject.toml

@@ -2,22 +2,21 @@
 
 [project]
 name = "aspyx_service"
-version = "0.9.0"
-description = "Service framework on top of aspyx"
+version = "0.10.0"
+description = "Aspyx Service framework"
 authors = [{ name = "Andreas Ernst", email = "andreas.ernst7@gmail.com" }]
 readme = "README.md"
 license = { file = "LICENSE" }
 requires-python = ">=3.9"
 dependencies = [
-    "aspyx>=1.4.1",
+    "aspyx>=1.5.0",
     "python-consul2~=0.1.5",
     "fastapi~=0.115.13",
     "httpx~=0.28.1",
-    "msgpack~=1.1.1"
+    "msgpack~=1.1.1",
+    "uvicorn[standard]"
 ]
 
-#"aspyx @ file://../aspyx",  # Local editable ref
-
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

{aspyx_service-0.9.0 → aspyx_service-0.10.0}/src/aspyx_service/__init__.py

@@ -4,7 +4,7 @@ This module provides the core Aspyx service management framework allowing for se
 
 from aspyx.di import module
 
-from .service import ServiceException, Server, Channel, ComponentDescriptor, inject_service, ChannelAddress, ServiceAddress, ServiceManager, Component, Service, AbstractComponent, ComponentStatus, ComponentRegistry, implementation, health, component, service
+from .service import ServiceException, Server, Channel, ComponentDescriptor, inject_service, ChannelAddress, ChannelInstances, ServiceManager, Component, Service, AbstractComponent, ComponentStatus, ComponentRegistry, implementation, health, component, service
 from .channels import HTTPXChannel, DispatchJSONChannel
 from .registries import ConsulComponentRegistry
 from .server import FastAPIServer
@@ -32,7 +32,7 @@ __all__ = [
     "ComponentDescriptor",
     "ComponentRegistry",
     "ChannelAddress",
-    "ServiceAddress",
+    "ChannelInstances",
     "health",
     "component",
     "service",
@@ -41,6 +41,11 @@ __all__ = [
 
     # healthcheck
 
+    "health_checks",
+    "health_check",
+    "HealthStatus",
+    "HealthCheckManager",
+
     # serialization
 
    # "deserialize",

{aspyx_service-0.9.0 → aspyx_service-0.10.0}/src/aspyx_service/channels.py

@@ -12,7 +12,7 @@ from pydantic import BaseModel
 from aspyx.reflection import DynamicProxy, TypeDescriptor
 from .service import ServiceManager
 
-from .service import ComponentDescriptor, ServiceAddress, ServiceException, channel, Channel, RemoteServiceException
+from .service import ComponentDescriptor, ChannelInstances, ServiceException, channel, Channel, RemoteServiceException
 from .serialization import get_deserializer
 
 
@@ -26,8 +26,8 @@ class HTTPXChannel(Channel):
 
     # constructor
 
-    def __init__(self, name):
-        super().__init__(name)
+    def __init__(self):
+        super().__init__()
 
         self.client: Optional[Client] = None
         self.async_client: Optional[AsyncClient] = None
@@ -49,7 +49,7 @@ class HTTPXChannel(Channel):
 
     # override
 
-    def setup(self, component_descriptor: ComponentDescriptor, address: ServiceAddress):
+    def setup(self, component_descriptor: ComponentDescriptor, address: ChannelInstances):
         super().setup(component_descriptor, address)
 
         # remember service names
@@ -92,21 +92,25 @@ class Response(BaseModel):
 
 @channel("dispatch-json")
 class DispatchJSONChannel(HTTPXChannel):
+    """
+    A channel that calls a POST on th endpoint `ìnvoke` sending a request body containing information on the
+    called component, service and method and the arguments.
+    """
     # constructor
 
     def __init__(self):
-        super().__init__("dispatch-json")
+        super().__init__()
 
     # internal
 
     # implement Channel
 
-    def set_address(self, address: Optional[ServiceAddress]):
+    def set_address(self, address: Optional[ChannelInstances]):
         ServiceManager.logger.info("channel %s got an address %s", self.name, address)
 
         super().set_address(address)
 
-    def setup(self, component_descriptor: ComponentDescriptor, address: ServiceAddress):
+    def setup(self, component_descriptor: ComponentDescriptor, address: ChannelInstances):
         super().setup(component_descriptor, address)
 
     def invoke(self, invocation: DynamicProxy.Invocation):
@@ -146,14 +150,17 @@ class DispatchJSONChannel(HTTPXChannel):
 
 @channel("dispatch-msgpack")
 class DispatchMSPackChannel(HTTPXChannel):
+    """
+    A channel that sends a POST on the ìnvoke `endpoint`with an msgpack encoded request body.
+    """
     # constructor
 
     def __init__(self):
-        super().__init__("dispatch-msgpack")
+        super().__init__()
 
     # override
 
-    def set_address(self, address: Optional[ServiceAddress]):
+    def set_address(self, address: Optional[ChannelInstances]):
         ServiceManager.logger.info("channel %s got an address %s", self.name, address)
 
         super().set_address(address)
@@ -207,4 +214,3 @@ class DispatchMSPackChannel(HTTPXChannel):
 
         except Exception as e:
             raise ServiceException(f"msgpack exception: {e}") from e
-

{aspyx_service-0.9.0 → aspyx_service-0.10.0}/src/aspyx_service/healthcheck.py

@@ -9,7 +9,7 @@ import time
 from enum import Enum
 from typing import Any, Callable, Type, Optional
 
-from aspyx.di import Providers, ClassInstanceProvider, injectable, Environment, inject_environment, on_init
+from aspyx.di import injectable, Environment, inject_environment, on_init
 from aspyx.reflection import Decorators, TypeDescriptor
 
 
@@ -31,7 +31,8 @@ def health_checks():
 
 def health_check(name="", cache = 0, fail_if_slower_than = 0):
     """
-    Methods annotated with `@on_init` will be called when the instance is created."""
+    Methods annotated with `@on_init` will be called when the instance is created.
+    """
     def decorator(func):
         Decorators.add(func, health_check, name, cache, fail_if_slower_than)
         return func
@@ -39,6 +40,13 @@ def health_check(name="", cache = 0, fail_if_slower_than = 0):
     return decorator
 
 class HealthStatus(Enum):
+    """
+    A enum specifying the health status of a service. The values are:
+
+    - `OK` service is healthy
+    - `WARNING` service has some problems
+    - `CRITICAL` service is unhealthy
+    """
     OK = 1
     WARNING = 2
     ERROR = 3
@@ -49,6 +57,9 @@ class HealthStatus(Enum):
 
 @injectable()
 class HealthCheckManager:
+    """
+    The health manager is able to run all registered health checks and is able to return an overall status.
+    """
     logger = logging.getLogger("aspyx.service.health")
 
     # local classes
@@ -112,8 +123,8 @@ class HealthCheckManager:
             return result
 
     class Health:
-        def __init__(self):
-            self.status = HealthStatus.OK
+        def __init__(self, status: HealthStatus = HealthStatus.OK):
+            self.status = status
             self.results : list[HealthCheckManager.Result] = []
 
         def to_dict(self):
@@ -135,6 +146,11 @@ class HealthCheckManager:
     # check
 
     async def check(self) -> HealthCheckManager.Health:
+        """
+        run all registered health checks and return an overall result.
+        Returns: the overall result.
+
+        """
         self.logger.info("Checking health...")
 
         health = HealthCheckManager.Health()

{aspyx_service-0.9.0 → aspyx_service-0.10.0}/src/aspyx_service/registries.py

@@ -15,9 +15,13 @@ from aspyx.di import on_init
 from .healthcheck import HealthCheckManager, HealthStatus
 
 from .server import Server
-from .service import ComponentRegistry, Channel, ServiceAddress, ServiceManager, ComponentDescriptor, Component, ChannelAddress
+from .service import ComponentRegistry, Channel, ChannelInstances, ServiceManager, ComponentDescriptor, Component, ChannelAddress
 
 class ConsulComponentRegistry(ComponentRegistry):
+    """
+    A specialized registry using consul.
+    A polling mechanism is used to identify changes in the component health.
+    """
     # constructor
 
     def __init__(self, port: int, consul_url: str):
@@ -28,7 +32,7 @@ class ConsulComponentRegistry(ComponentRegistry):
         self.watchdog = None
         self.interval = 5
         self.last_index = {}
-        self.component_addresses : dict[str, dict[str, ServiceAddress]] = {} # comp -> channel -> address
+        self.component_addresses : dict[str, dict[str, ChannelInstances]] = {} # comp -> channel -> address
         self.watch_channels : list[Channel] = []
 
         parsed = urlparse(consul_url)
@@ -36,7 +40,18 @@ class ConsulComponentRegistry(ComponentRegistry):
         self.consul_host = parsed.hostname
         self.consul_port = parsed.port
 
-    def make_consul(self, host: str, port: int) -> consul.Consul:
+    def make_consul(self, host="", port="") -> consul.Consul:
+        """
+        create and return a consul instance
+
+        Args:
+            host: the host
+            port: the port
+
+        Returns:
+            a consul instance
+
+        """
         return consul.Consul(host=host, port=port)
 
     # lifecycle hooks
@@ -53,7 +68,7 @@ class ConsulComponentRegistry(ComponentRegistry):
         self.watchdog = threading.Thread(target=self.watch_consul, daemon=True)
         self.watchdog.start()
 
-    def inform_channels(self, old_address: ServiceAddress, new_address: Optional[ServiceAddress]):
+    def inform_channels(self, old_address: ChannelInstances, new_address: Optional[ChannelInstances]):
         for channel in self.watch_channels:
             if channel.address is old_address:
                 channel.set_address(new_address)
@@ -110,16 +125,14 @@ class ConsulComponentRegistry(ComponentRegistry):
             time.sleep(5)
 
     @abstractmethod
-    def watch(self, channel: Channel):
+    def watch(self, channel: Channel) -> None:
         self.watch_channels.append(channel)
 
         #self.component_addresses[channel.component_descriptor.name] = {}
 
    # public
 
-    def register_service(self, name, service_id, health: str, tags=None, meta=None):
-        ip = "host.docker.internal" # TODO
-
+    def register_service(self, name, service_id, health: str, tags=None, meta=None) -> None:
         self.consul.agent.service.register(
             name=name,
             service_id=service_id,
@@ -128,13 +141,13 @@ class ConsulComponentRegistry(ComponentRegistry):
             tags=tags or [],
             meta=meta or {},
             check=consul.Check().http(
-                url=f"http://{ip}:{self.port}{health}",
+                url=f"http://{self.ip}:{self.port}{health}",
                 interval="10s",
                 timeout="3s",
                 deregister="5m")
             )
 
-    def deregister(self, descriptor: ComponentDescriptor[Component]):
+    def deregister(self, descriptor: ComponentDescriptor[Component]) -> None:
         name = descriptor.name
 
         service_id = f"{self.ip}:{self.port}:{name}"
@@ -149,8 +162,8 @@ class ConsulComponentRegistry(ComponentRegistry):
 
     # private
 
-    def fetch_addresses(self, component: str, wait=None) -> dict[str, ServiceAddress]:
-        addresses : dict[str, ServiceAddress] = {} # channel name -> ServiceAddress
+    def fetch_addresses(self, component: str, wait=None) -> dict[str, ChannelInstances]:
+        addresses : dict[str, ChannelInstances] = {} # channel name -> ServiceAddress
 
         index, nodes = self.consul.health.service(component, passing=True, index=self.last_index.get(component, None), wait=wait)
         self.last_index[component] = index
@@ -170,7 +183,7 @@ class ConsulComponentRegistry(ComponentRegistry):
 
                 address = addresses.get(channel, None)
                 if address is None:
-                    address = ServiceAddress(component=component, channel=channel_name)
+                    address = ChannelInstances(component=component, channel=channel_name)
                     addresses[channel] = address
 
                 address.urls.append(url)
@@ -200,7 +213,7 @@ class ConsulComponentRegistry(ComponentRegistry):
 
         self.register_service(name, id, descriptor.health, tags =["component"], meta={"channels": addresses})
 
-    def get_addresses(self, descriptor: ComponentDescriptor) -> list[ServiceAddress]:
+    def get_addresses(self, descriptor: ComponentDescriptor) -> list[ChannelInstances]:
         component_addresses = self.component_addresses.get(descriptor.name, None)
         if component_addresses is None:
             component_addresses = self.fetch_addresses(descriptor.name)

{aspyx_service-0.9.0 → aspyx_service-0.10.0}/src/aspyx_service/restchannel.py

@@ -1,3 +1,6 @@
+"""
+rest channel implementation
+"""
 import inspect
 import re
 from dataclasses import is_dataclass, asdict
@@ -7,7 +10,7 @@ from typing import get_type_hints, TypeVar, Annotated, Callable, get_origin, get
 from pydantic import BaseModel
 
 from aspyx.reflection import DynamicProxy, Decorators
-from .service import RemoteServiceException, ServiceException, channel
+from .service import ServiceException, channel
 
 T = TypeVar("T")
 
@@ -25,14 +28,26 @@ QueryParam = lambda t: Annotated[t, QueryParamMarker]
 
 # decorators
 
-def rest(url):
+def rest(url=""):
+    """
+    mark service interfaces to add a url prefix
+
+    Args:
+        url: prefix that will be added to all urls
+    """
     def decorator(cls):
         Decorators.add(cls, rest, url)
 
         return cls
     return decorator
 
-def get(url):
+def get(url: str):
+    """
+    methods marked with `get` will be executed by calling a http get request.
+
+    Args:
+        url: the url
+    """
     def decorator(cls):
         Decorators.add(cls, get, url)
 
@@ -40,7 +55,14 @@ def get(url):
     return decorator
 
 
-def post(url):
+def post(url: str):
+    """
+    methods marked with `post` will be executed by calling a http get request.
+    The body parameter should be marked with `Body(<param>)`
+
+    Args:
+        url: the url
+    """
     def decorator(cls):
         Decorators.add(cls, post, url)
 
@@ -48,7 +70,13 @@ def post(url):
 
     return decorator
 
-def put(url):
+def put(url: str):
+    """
+    methods marked with `put` will be executed by calling a http put request.
+
+    Args:
+        url: the url
+    """
     def decorator(cls):
         Decorators.add(cls, put, url)
 
@@ -56,7 +84,13 @@ def put(url):
 
     return decorator
 
-def delete(url):
+def delete(url: str):
+    """
+    methods marked with `delete` will be executed by calling a http delete request.
+
+    Args:
+        url: the url
+    """
     def decorator(cls):
         Decorators.add(cls, delete, url)
 
@@ -64,7 +98,13 @@ def delete(url):
 
     return decorator
 
-def patch(url):
+def patch(url: str):
+    """
+    methods marked with `patch` will be executed by calling a http patch request.
+
+    Args:
+        url: the url
+    """
     def decorator(cls):
         Decorators.add(cls, patch, url)
 
@@ -72,20 +112,22 @@ def patch(url):
 
     return decorator
 
-
-
-
 @channel("rest")
 class RestChannel(HTTPXChannel):
+    """
+    A rest channel executes http requests as specified by the corresponding decorators and annotations,
+    """
     __slots__ = [
         "signature",
         "url_template",
         "type",
+        "calls",
         "return_type",
         "path_param_names",
         "query_param_names",
         "body_param_name"
     ]
+
     # local class
 
     class Call:
@@ -133,7 +175,7 @@ class RestChannel(HTTPXChannel):
     # constructor
 
     def __init__(self):
-        super().__init__("rest")
+        super().__init__()
 
         self.calls : dict[Callable, RestChannel.Call] = {}
 
@@ -196,4 +238,4 @@ class RestChannel(HTTPXChannel):
                 raise ServiceException(
                     f"no url for channel {self.name} for component {self.component_descriptor.name} registered")
         except Exception as e:
-            raise ServiceException(f"communication exception {e}") from e
+            raise ServiceException(f"communication exception {e}") from e

{aspyx_service-0.9.0 → aspyx_service-0.10.0}/src/aspyx_service/serialization.py

@@ -98,7 +98,7 @@ class TypeDeserializer:
             return deser_union
 
         if isinstance(typ, type) and issubclass(typ, BaseModel):
-            return lambda v: typ.parse_obj(v)
+            return typ.parse_obj
 
         if is_dataclass(typ):
             field_deserializers = {f.name: TypeDeserializer(f.type) for f in fields(typ)}
@@ -122,4 +122,13 @@ class TypeDeserializer:
 
 @lru_cache(maxsize=512)
 def get_deserializer(typ):
+    """
+    return a function that is able to deserialize a value of the specified type
+
+    Args:
+        typ: the type
+
+    Returns:
+
+    """
     return TypeDeserializer(typ)

{aspyx_service-0.9.0 → aspyx_service-0.10.0}/src/aspyx_service/server.py

@@ -2,7 +2,6 @@
 FastAPI server implementation for the aspyx service framework.
 """
 import atexit
-import functools
 import inspect
 import threading
 from typing import Type, Optional, Callable
@@ -28,6 +27,9 @@ from .restchannel import get, post, put, delete, rest
 
 
 class FastAPIServer(Server):
+    """
+    A server utilizing fastapi framework.
+    """
     # constructor
 
     def __init__(self, host="0.0.0.0", port=8000, **kwargs):
@@ -41,7 +43,7 @@ class FastAPIServer(Server):
         self.component_registry: Optional[ComponentRegistry] = None
 
         self.router = APIRouter()
-        self.fast_api = FastAPI(host=self.host, port=Server.port, debug=True)
+        self.fast_api = FastAPI()
 
         # cache
 
@@ -82,14 +84,21 @@ class FastAPIServer(Server):
                         )
 
     def start(self):
-        def run():
-            uvicorn.run(self.fast_api, host=self.host, port=self.port, access_log=False)
+        """
+        start the fastapi server in a thread
+        """
+
+        config = uvicorn.Config(self.fast_api, host=self.host, port=self.port, log_level="info")
+        server = uvicorn.Server(config)
 
-        self.server_thread = threading.Thread(target=run, daemon=True)
-        self.server_thread.start()
+        thread = threading.Thread(target=server.run, daemon=True)
+        thread.start()
 
         print(f"server started on {self.host}:{self.port}")
 
+        return thread
+
+
     def get_deserializers(self, service: Type, method):
         deserializers = self.deserializers.get(method, None)
         if deserializers is None:
@@ -105,8 +114,8 @@ class FastAPIServer(Server):
 
         deserializers = self.get_deserializers(type, method)
 
-        for i in range(0, len(args)):
-            args[i] = deserializers[i](args[i])
+        for i, arg in enumerate(args):
+            args[i] = deserializers[i](arg)
 
         return args
 
@@ -181,6 +190,15 @@ class FastAPIServer(Server):
         self.router.get(url)(get_health_response)
 
     def boot(self, module_type: Type) -> Environment:
+        """
+        startup the service manager, DI framework and the fastapi server based on the supplied module
+
+        Args:
+            module_type: the module
+
+        Returns:
+
+        """
         # setup environment
 
         self.environment = Environment(module_type)
@@ -194,8 +212,8 @@ class FastAPIServer(Server):
         self.add_routes()
         self.fast_api.include_router(self.router)
 
-        #for route in self.fast_api.routes:
-        #    print(f"{route.name}: {route.path} [{route.methods}]")
+        for route in self.fast_api.routes:
+            print(f"{route.name}: {route.path} [{route.methods}]")
 
         # start server thread
 

{aspyx_service-0.9.0 → aspyx_service-0.10.0}/src/aspyx_service/service.py

@@ -3,6 +3,7 @@ service management framework allowing for service discovery and transparent remo
 """
 from __future__ import annotations
 
+import re
 import socket
 import logging
 import threading
@@ -24,11 +25,10 @@ class Service:
     """
     This is something like a 'tagging interface' for services.
     """
-    pass
 
 class ComponentStatus(Enum):
     """
-    A component is ij one of the following status:
+    A component is in one of the following statuses:
 
     - VIRGIN: just constructed
     - RUNNING: registered and up and running
@@ -41,7 +41,7 @@ class ComponentStatus(Enum):
 class Server(ABC):
     """
     A server is a central entity that boots a main module and initializes the ServiceManager.
-    It also is the place where http servers get initialized,
+    It also is the place where http servers get initialized.
     """
     port = 0
 
@@ -64,6 +64,11 @@ class Server(ABC):
 
     @classmethod
     def get_local_ip(cls):
+        """
+        return the local ip address
+
+        Returns: the local ip address
+        """
         try:
             # create a dummy socket to an external address
 
@@ -72,8 +77,7 @@ class Server(ABC):
             ip = s.getsockname()[0]
             s.close()
 
-            raise Exception("TODO")
-            #return ip
+            return ip
         except Exception:
             return "127.0.0.1"  # Fallback
 
@@ -98,24 +102,44 @@ class Component(Service):
     This is the base class for components.
     """
     @abstractmethod
-    def startup(self):
-        pass
+    def startup(self) -> None:
+        """
+        startup callback
+        """
 
     @abstractmethod
-    def shutdown(self):
-        pass
+    def shutdown(self)-> None:
+        """
+        shutdown callback
+        """
 
     @abstractmethod
     def get_addresses(self, port: int) -> list[ChannelAddress]:
-        pass
+        """
+        returns a list of channel addresses that expose this components services.
+
+        Args:
+            port: the port of a server hosting this component
+
+        Returns:
+            list of channel addresses
+        """
 
     @abstractmethod
     def get_status(self) -> ComponentStatus:
-        pass
+        """
+        return the component status callback
+
+        Returns: the component status
+        """
 
     @abstractmethod
     async def get_health(self) -> HealthCheckManager.Health:
-        pass
+        """
+        return the component health
+
+        Returns: the component health
+        """
 
 class AbstractComponent(Component, ABC):
     """
@@ -126,18 +150,33 @@ class AbstractComponent(Component, ABC):
     def __init__(self):
         self.status = ComponentStatus.VIRGIN
 
-    def startup(self):
+    def startup(self) -> None:
         self.status = ComponentStatus.RUNNING
 
-    def shutdown(self):
+    def shutdown(self) -> None:
         self.status = ComponentStatus.STOPPED
 
-    def get_status(self):
+    def get_status(self) -> ComponentStatus:
         return self.status
 
+def to_snake_case(name: str) -> str:
+    return re.sub(r'(?<!^)(?=[A-Z])', '-', name).lower()
+
 def component(name = "", description="", services: list[Type] = []):
+    """
+    decorates component interfaces
+
+    Args:
+        name: the component name. If empty the class name converted to snake-case is used
+        description: optional description
+        services: the list of hosted services
+    """
     def decorator(cls):
-        Decorators.add(cls, component, name, description, services)
+        component_name = name
+        if component_name == "":
+            component_name = to_snake_case(cls.__name__)
+
+        Decorators.add(cls, component, component_name, description, services)
 
         ServiceManager.register_component(cls, services)
 
@@ -148,8 +187,19 @@ def component(name = "", description="", services: list[Type] = []):
     return decorator
 
 def service(name = "", description = ""):
+    """
+    decorates service interfaces
+
+    Args:
+        name: the service name. If empty the class name converted to snake case is used
+        description: optional description
+    """
     def decorator(cls):
-        Decorators.add(cls, service, name, description)
+        service_name = name
+        if service_name == "":
+            service_name = to_snake_case(cls.__name__)
+
+        Decorators.add(cls, service, service_name, description)
 
         Providers.register(ServiceInstanceProvider(cls))
 
@@ -157,16 +207,24 @@ def service(name = "", description = ""):
 
     return decorator
 
+def health(endpoint = ""):
+    """
+    specifies the health endpoint that will return the component health
 
-def health(name = ""):
+    Args:
+        endpoint: the  health endpoint
+    """
     def decorator(cls):
-        Decorators.add(cls, health, name)
+        Decorators.add(cls, health, endpoint)
 
         return cls
 
     return decorator
 
 def implementation():
+    """
+    decorates service or component implementations.
+    """
     def decorator(cls):
         Decorators.add(cls, implementation)
 
@@ -299,7 +357,14 @@ class ComponentDescriptor(BaseDescriptor[T]):
 # a resolved channel address
 
 @dataclass()
-class ServiceAddress:
+class ChannelInstances:
+    """
+    a resolved channel address containing:
+
+    - component: the component name
+    - channel: the channel name
+    - urls: list of URLs
+    """
     component: str
     channel: str
     urls: list[str]
@@ -312,18 +377,29 @@ class ServiceAddress:
         self.urls : list[str] = sorted(urls)
 
 class ServiceException(Exception):
-    pass
+    """
+    base class for service exceptions
+    """
 
 class LocalServiceException(ServiceException):
-    pass
+    """
+    base class for service exceptions occurring locally
+    """
 
 class ServiceCommunicationException(ServiceException):
-    pass
+    """
+    base class for service exceptions thrown by remoting errors
+    """
 
 class RemoteServiceException(ServiceException):
-    pass
+    """
+    base class for service exceptions occurring on the server side
+    """
 
 class Channel(DynamicProxy.InvocationHandler, ABC):
+    """
+    A channel is a dynamic proxy invocation handler and transparently takes care of remoting.
+    """
     __slots__ = [
         "name",
         "component_descriptor",
@@ -331,11 +407,25 @@ class Channel(DynamicProxy.InvocationHandler, ABC):
     ]
 
     class URLSelector:
+        """
+        a url selector retrieves a URL for the next remoting call.
+        """
         @abstractmethod
         def get(self, urls: list[str]) -> str:
-            pass
+            """
+            return the next URL given a list of possible URLS
+
+            Args:
+                urls: list of possible URLS
+
+            Returns:
+                a URL
+            """
 
     class FirstURLSelector(URLSelector):
+        """
+        a url selector always retrieving the first URL given a list of possible URLS
+        """
         def get(self, urls: list[str]) -> str:
             if len(urls) == 0:
                 raise ServiceCommunicationException("no known url")
@@ -343,6 +433,9 @@ class Channel(DynamicProxy.InvocationHandler, ABC):
             return urls[0]
 
     class RoundRobinURLSelector(URLSelector):
+        """
+        a url selector that picks urls sequentially given a list of possible URLS
+        """
         def __init__(self):
             self.index = 0
 
@@ -358,59 +451,90 @@ class Channel(DynamicProxy.InvocationHandler, ABC):
 
     # constructor
 
-    def __init__(self, name: str):
-        self.name = name
+    def __init__(self):
+        self.name =  Decorators.get_decorator(type(self), channel).args[0]
         self.component_descriptor : Optional[ComponentDescriptor] = None
-        self.address: Optional[ServiceAddress] = None
-        self.url_provider : Channel.URLSelector = Channel.FirstURLSelector()
+        self.address: Optional[ChannelInstances] = None
+        self.url_selector : Channel.URLSelector = Channel.FirstURLSelector()
 
     # public
 
     def customize(self):
         pass
 
-    def select_round_robin(self):
-        self.url_provider = Channel.RoundRobinURLSelector()
+    def select_round_robin(self) -> None:
+        """
+        enable round robin
+        """
+        self.url_selector = Channel.RoundRobinURLSelector()
 
     def select_first_url(self):
-        self.url_provider = Channel.FirstURLSelector()
+        """
+        pick the first URL
+        """
+        self.url_selector = Channel.FirstURLSelector()
 
     def get_url(self) -> str:
-        return self.url_provider.get(self.address.urls)
+        return self.url_selector.get(self.address.urls)
 
-    def set_address(self, address: Optional[ServiceAddress]):
+    def set_address(self, address: Optional[ChannelInstances]):
         self.address = address
 
-    def setup(self, component_descriptor: ComponentDescriptor, address: ServiceAddress):
+    def setup(self, component_descriptor: ComponentDescriptor, address: ChannelInstances):
         self.component_descriptor = component_descriptor
         self.address = address
 
 
 class ComponentRegistry:
+    """
+    A component registry keeps track of components including their health
+    """
     @abstractmethod
-    def register(self, descriptor: ComponentDescriptor[Component], addresses: list[ChannelAddress]):
-        pass
+    def register(self, descriptor: ComponentDescriptor[Component], addresses: list[ChannelAddress]) -> None:
+        """
+        register a component to the registry
+        Args:
+            descriptor: the descriptor
+            addresses: list of addresses
+        """
 
     @abstractmethod
-    def deregister(self, descriptor: ComponentDescriptor[Component]):
-        pass
+    def deregister(self, descriptor: ComponentDescriptor[Component]) -> None:
+        """
+        deregister a component from the registry
+        Args:
+            descriptor: the component descriptor
+        """
 
     @abstractmethod
-    def watch(self, channel: Channel):
-        pass
+    def watch(self, channel: Channel) -> None:
+        """
+        remember the passed channel and keep it informed about address changes
+        Args:
+            channel: a channel
+        """
 
     @abstractmethod
-    def get_addresses(self, descriptor: ComponentDescriptor) -> list[ServiceAddress]:
-        pass
+    def get_addresses(self, descriptor: ComponentDescriptor) -> list[ChannelInstances]:
+        """
+        return a list of addresses that can be used to call services belonging to this component
+
+        Args:
+            descriptor: the component descriptor
+
+        Returns:
+            list of channel instances
+        """
 
     def map_health(self, health:  HealthCheckManager.Health) -> int:
         return 200
 
-    def shutdown(self):
-        pass
 
 @injectable()
 class ChannelManager:
+    """
+    Internal factory for channels.
+    """
     factories: dict[str, Type] = {}
 
     @classmethod
@@ -432,7 +556,7 @@ class ChannelManager:
 
     # public
 
-    def make(self, name: str, descriptor: ComponentDescriptor, address: ServiceAddress) -> Channel:
+    def make(self, name: str, descriptor: ComponentDescriptor, address: ChannelInstances) -> Channel:
         ServiceManager.logger.info("create channel %s: %s", name, self.factories.get(name).__name__)
 
         result =  self.environment.get(self.factories.get(name))
@@ -441,7 +565,13 @@ class ChannelManager:
 
         return result
 
-def channel(name):
+def channel(name: str):
+    """
+    this decorator is used to mark channel implementations.
+
+    Args:
+        name: the channel name
+    """
     def decorator(cls):
         Decorators.add(cls, channel, name)
 
@@ -460,6 +590,9 @@ class TypeAndChannel:
 
 @injectable()
 class ServiceManager:
+    """
+    Central class that manages services and components and is able to return proxies.
+    """
     # class property
 
     logger = logging.getLogger("aspyx.service")  # __name__ = module name
@@ -587,7 +720,7 @@ class ServiceManager:
 
     # public
 
-    def find_service_address(self, component_descriptor: ComponentDescriptor, preferred_channel="") -> ServiceAddress:
+    def find_service_address(self, component_descriptor: ComponentDescriptor, preferred_channel="") -> ChannelInstances:
         addresses = self.component_registry.get_addresses(component_descriptor)  # component, channel + urls
         address = next((address for address in addresses if address.channel == preferred_channel), None)
         if address is None:
@@ -600,6 +733,16 @@ class ServiceManager:
         return address
 
     def get_service(self, service_type: Type[T], preferred_channel="") -> T:
+        """
+        return a service proxy given a service type and preferred channel name
+
+        Args:
+            service_type:  the service type
+            preferred_channel:  the preferred channel name
+
+        Returns:
+            the proxy
+        """
         service_descriptor = ServiceManager.get_descriptor(service_type)
         component_descriptor = service_descriptor.get_component_descriptor()
 
@@ -688,7 +831,7 @@ class LocalChannel(Channel):
     # constructor
 
     def __init__(self, manager: ServiceManager):
-        super().__init__("local")
+        super().__init__()
 
         self.manager = manager
         self.component = component
@@ -717,16 +860,16 @@ class LocalComponentRegistry(ComponentRegistry):
 
     # implement
 
-    def register(self, descriptor: ComponentDescriptor[Component], addresses: list[ChannelAddress]):
+    def register(self, descriptor: ComponentDescriptor[Component], addresses: list[ChannelAddress]) -> None:
         self.component_channels[descriptor] = addresses
 
-    def deregister(self, descriptor: ComponentDescriptor[Component]):
+    def deregister(self, descriptor: ComponentDescriptor[Component]) -> None:
         pass
 
-    def watch(self, channel: Channel):
+    def watch(self, channel: Channel) -> None:
         pass
 
-    def get_addresses(self, descriptor: ComponentDescriptor) -> list[ServiceAddress]:
+    def get_addresses(self, descriptor: ComponentDescriptor) -> list[ChannelInstances]:
         return self.component_channels.get(descriptor, [])
 
 def inject_service(preferred_channel=""):

{aspyx_service-0.9.0 → aspyx_service-0.10.0}/tests/test-service.py

@@ -1,3 +1,6 @@
+"""
+Tests
+"""
 import asyncio
 import logging
 import threading
@@ -5,8 +8,7 @@ import time
 from abc import abstractmethod
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Dict, cast, Optional, Callable
-import atexit
+from typing import Dict, cast, Optional
 
 import consul
 import httpx
@@ -18,7 +20,7 @@ from aspyx.di.configuration import YamlConfigurationSource
 from aspyx_service import ConsulComponentRegistry, service, Service, component, Component, \
     implementation, health, AbstractComponent, ChannelAddress, inject_service, \
     FastAPIServer, Server, ServiceModule, DispatchJSONChannel, ServiceManager, ComponentDescriptor, health_checks, \
-    check, HealthCheckManager, HealthStatus
+    health_check, HealthCheckManager, get, post, Body, rest
 
 # configure logging
 
@@ -27,15 +29,15 @@ logging.basicConfig(
     format='[%(asctime)s] %(levelname)s in %(filename)s:%(lineno)d - %(message)s'
 )
 
-logging.getLogger("httpx").setLevel(logging.WARNING)
+logging.getLogger("httpx").setLevel(logging.ERROR)
 
 def configure_logging(levels: Dict[str, int]) -> None:
     for name in levels:
         logging.getLogger(name).setLevel(levels[name])
 
 configure_logging({
-    "aspyx.di": logging.DEBUG,
-    "aspyx.service": logging.DEBUG
+    "aspyx.di": logging.INFO,
+    "aspyx.service": logging.INFO
 })
 
 # just a test
@@ -65,7 +67,7 @@ class ChannelAdvice:
     def make_client(self, invocation: Invocation):
         rest_channel = cast(DispatchJSONChannel, invocation.args[0])
 
-        rest_channel.round_robin()
+        rest_channel.select_round_robin()
 
         return InterceptingClient()
 
@@ -117,8 +119,10 @@ data = Data("data-0", "data-1", "data-2", "data-3", "data-4", "data-5", "data-6"
 )
 
 @service(name="test-service", description="cool")
+@rest("/api")
 class TestService(Service):
     @abstractmethod
+    @get("/hello/{message}")
     def hello(self, message: str) -> str:
         pass
 
@@ -126,14 +130,15 @@ class TestService(Service):
     async def hello_async(self, message: str) -> str:
         pass
 
-    def data(self, data: Data) -> Data:
+    @post("/data/")
+    def data(self, data: Body(Data)) -> Data:
         pass
 
     async def data_async(self, data: Data) -> Data:
         pass
 
-@component(name="test-component", services =[TestService])
-class TestComponent(Component):
+@component(services =[TestService])
+class TestComponent(Component): # pylint: disable=abstract-method
     pass
 
 # implementation classes
@@ -144,17 +149,15 @@ class TestServiceImpl(TestService):
         pass
 
     def hello(self, message: str) -> str:
-        #print(f"hello {message}")
         return f"hello {message}"
 
     async def hello_async(self, message: str) -> str:
-        #print(f"hello {message}")
         return f"hello {message}"
 
     def data(self, data: Data) -> Data:
         return data
 
-    def data_async(self, data: Data) -> Data:
+    async def data_async(self, data: Data) -> Data:
         return data
 
 @implementation()
@@ -175,19 +178,20 @@ class TestComponentImpl(AbstractComponent, TestComponent):
 
     # implement
 
-    def get_health(self):
-        return self.health_check_manager.check()
+    async def get_health(self) -> HealthCheckManager.Health:
+        return await self.health_check_manager.check()
 
     def get_addresses(self, port: int) -> list[ChannelAddress]:
         return [
+            ChannelAddress("rest", f"http://{Server.get_local_ip()}:{port}"),
             ChannelAddress("dispatch-json", f"http://{Server.get_local_ip()}:{port}"),
             ChannelAddress("dispatch-msgpack", f"http://{Server.get_local_ip()}:{port}")
         ]
 
-    def startup(self):
+    def startup(self) -> None:
         print("### startup")
 
-    def shutdown(self):
+    def shutdown(self) -> None:
         print("### shutdown")
 
 @injectable()
@@ -195,28 +199,29 @@ class Bar:
     def __init__(self):
         pass
 
-@injectable()
+@injectable(eager=False)
 class Test:
     def __init__(self):
         self.service = None
 
-    #@inject_service() TODO
-    #def set_service(self, service: TestService):
-    #    self.service = service
-    #    print(service)
+    @inject_service(preferred_channel="")
+    def set_service(self, service: TestService, bla: str):
+        self.service = service
+        print(service)
 
 @health_checks()
+@injectable()
 class Checks:
     def __init__(self):
         pass
 
-    @check(fail_if_slower_than=1)
+    @health_check(fail_if_slower_than=1)
     def check_1(self, result: HealthCheckManager.Result):
         #result.set_status(HealthStatus.OK)
         #time.sleep(2)
         pass
 
-    @check(name="check-2", cache=10)
+    @health_check(name="check-2", cache=10)
     def check_2(self, result: HealthCheckManager.Result):
         pass # result.set_status(HealthStatus.OK)
 
@@ -247,11 +252,6 @@ async def main():
 
     service_manager = environment.get(ServiceManager)
 
-    def cleanup():
-        service_manager.shutdown()
-
-    atexit.register(cleanup)
-
     descriptor: ComponentDescriptor = cast(ComponentDescriptor, service_manager.get_descriptor(TestComponent))
 
     while True:
@@ -262,6 +262,10 @@ async def main():
         print("zzz...")
         time.sleep(1)
 
+    test_service = service_manager.get_service(TestService, preferred_channel="rest")
+
+    r = test_service.hello("world")
+
     test_service = service_manager.get_service(TestService, preferred_channel="dispatch-json")
     msgpack_test_service = service_manager.get_service(TestService, preferred_channel="dispatch-msgpack")
 
@@ -327,8 +331,38 @@ async def main():
         print(f"{title} {iterations} in {n_threads} threads: {took} ms, avg: {avg_ms}ms")
 
 
-    test_thread_test(title="sync call", n_threads=1, iterations=1000)
-    test_async_thread_test(title="async call",n_threads=1, iterations=1000)
+    #test_thread_test(title="sync call", n_threads=1, iterations=1000)
+    #test_async_thread_test(title="async call",n_threads=1, iterations=1000)
+
+    #####
+
+    test_service = service_manager.get_service(TestService, preferred_channel="rest")
+
+    loops = 1000
+    start = time.perf_counter()
+    for _ in range(loops):
+        test_service.data(data)
+        #test_service.hello("world")
+
+    end = time.perf_counter()
+
+    avg_ms = ((end - start) / loops) * 1000
+    print(f"Average time per rest call: {avg_ms:.3f} ms")
+
+    test_service = service_manager.get_service(TestService, preferred_channel="dispatch-msgpack")
+
+    loops = 1000
+    start = time.perf_counter()
+    for _ in range(loops):
+        #test_service.hello("andi")
+        test_service.data(data)
+
+    end = time.perf_counter()
+
+    avg_ms = ((end - start) / loops) * 1000
+    print(f"Average time per dispatch call: {avg_ms:.3f} ms")
+
+    return
 
     #####
 
@@ -387,9 +421,3 @@ async def main():
 if __name__ == "__main__":
     asyncio.run(main())
 
-
-
-
-
-
-