aspyx-service 0.9.0__py3-none-any.whl → 0.10.1__py3-none-any.whl

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=""):