iris-pex-embedded-python 3.7.2b2__py3-none-any.whl → 4.0.0__py3-none-any.whl

iop/production/component.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .common import (
+    _adapter_type_from_class_name,
+    _adapter_type_from_component_class,
+    _apply_settings_update,
+    _auto_proxy_class_name,
+    _bool_text,
+    _settings_to_iris,
+    _text_value,
+)
+from .types import TargetSetting, TargetSettingRef
+
+
+@dataclass
+class ComponentRef:
+    """Reference to a component item declared inside a Production."""
+
+    production: Any
+    name: str
+    component_class: type | None = None
+    class_name: str | None = None
+    adapter_class: type | None = None
+    adapter_class_name: str = ""
+    kind: str = "component"
+    category: str = ""
+    pool_size: int | str = 1
+    enabled: bool | str = True
+    foreground: bool | str = False
+    comment: str = ""
+    log_trace_events: bool | str = False
+    schedule: str = ""
+    host_settings: dict[str, Any] = field(default_factory=dict)
+    adapter_settings: dict[str, Any] = field(default_factory=dict)
+    other_settings: list[dict[str, Any]] = field(default_factory=list)
+    target_setting_names: set[str] = field(default_factory=set)
+    runtime_metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.class_name is None:
+            if self.component_class is None:
+                raise ValueError("component_class or class_name is required")
+            self.class_name = _auto_proxy_class_name(self.component_class)
+        if self.adapter_class is not None and not self.adapter_class_name:
+            self.adapter_class_name = _auto_proxy_class_name(self.adapter_class)
+        if not self.adapter_class_name:
+            self.adapter_class_name = _adapter_type_from_component_class(
+                self.component_class
+            )
+        if not self.adapter_class_name:
+            self.adapter_class_name = _adapter_type_from_class_name(self.class_name)
+
+    def __getattr__(self, name: str) -> TargetSettingRef:
+        if self.component_class is not None:
+            descriptor = getattr(self.component_class, name, None)
+            if isinstance(descriptor, TargetSetting):
+                return TargetSettingRef(
+                    production=self.production,
+                    component=self,
+                    name=name,
+                )
+        if name in self.target_setting_names:
+            return self.target_setting(name)
+        raise AttributeError(name)
+
+    def target_setting(self, name: str) -> TargetSettingRef:
+        self.target_setting_names.add(name)
+        return TargetSettingRef(
+            production=self.production,
+            component=self,
+            name=name,
+        )
+
+    def set_host_setting(self, name: str, value: Any) -> None:
+        self.host_settings[name] = value
+
+    def pool(self, size: int | str) -> ComponentRef:
+        self.pool_size = size
+        return self
+
+    def enable(self, enabled: bool | str = True) -> ComponentRef:
+        self.enabled = enabled
+        return self
+
+    def disable(self) -> ComponentRef:
+        return self.enable(False)
+
+    def run_foreground(self, enabled: bool | str = True) -> ComponentRef:
+        self.foreground = enabled
+        return self
+
+    def trace(self, enabled: bool | str = True) -> ComponentRef:
+        self.log_trace_events = enabled
+        return self
+
+    def schedule_on(self, schedule: str) -> ComponentRef:
+        self.schedule = schedule
+        return self
+
+    def comment_as(self, text: str) -> ComponentRef:
+        self.comment = text
+        return self
+
+    def category_as(self, category: str) -> ComponentRef:
+        self.category = category
+        return self
+
+    def host_setting(self, name: str, value: Any) -> ComponentRef:
+        _apply_settings_update(self.host_settings, {name: value})
+        return self
+
+    def host_settings_update(self, values: dict[str, Any]) -> ComponentRef:
+        _apply_settings_update(self.host_settings, values)
+        return self
+
+    def setting(self, name: str, value: Any) -> ComponentRef:
+        return self.host_setting(name, value)
+
+    def settings_update(self, values: dict[str, Any]) -> ComponentRef:
+        return self.host_settings_update(values)
+
+    def adapter_setting(self, name: str, value: Any) -> ComponentRef:
+        _apply_settings_update(self.adapter_settings, {name: value})
+        return self
+
+    def adapter_settings_update(self, values: dict[str, Any]) -> ComponentRef:
+        _apply_settings_update(self.adapter_settings, values)
+        return self
+
+    def other_setting(
+        self,
+        target: str,
+        name: str,
+        value: Any,
+    ) -> ComponentRef:
+        if target == "Host":
+            return self.host_setting(name, value)
+        if target == "Adapter":
+            return self.adapter_setting(name, value)
+
+        self.other_settings = [
+            setting
+            for setting in self.other_settings
+            if not (
+                setting.get("@Target") == target
+                and setting.get("@Name") == name
+            )
+        ]
+        if value is not None:
+            self.other_settings.append(
+                {
+                    "@Target": target,
+                    "@Name": name,
+                    "#text": _text_value(value),
+                }
+            )
+        return self
+
+    def connect(
+        self,
+        target_setting: str | TargetSettingRef,
+        target_component: ComponentRef | str | None = None,
+        **kwargs: Any,
+    ) -> ComponentRef:
+        target_setting_ref = self._coerce_target_setting_ref(target_setting)
+        self.production.connect(target_setting_ref, target_component, **kwargs)
+        return self
+
+    def _coerce_target_setting_ref(
+        self,
+        target_setting: str | TargetSettingRef,
+    ) -> TargetSettingRef:
+        if isinstance(target_setting, TargetSettingRef):
+            if target_setting.production is not self.production:
+                raise ValueError(
+                    "source target setting belongs to a different Production"
+                )
+            if target_setting.component is not self:
+                raise ValueError(
+                    "source target setting belongs to a different component"
+                )
+            return target_setting
+        return self.target_setting(str(target_setting))
+
+    def inspect(self, *, refresh: bool = True) -> dict[str, Any]:
+        return self.production.inspect_component(self, refresh=refresh)
+
+    def start(self) -> None:
+        self.production.start_component(self)
+
+    def stop(self) -> None:
+        self.production.stop_component(self)
+
+    def restart(self) -> None:
+        self.production.restart_component(self)
+
+    def test(
+        self,
+        message: Any = None,
+        *,
+        classname: str | None = None,
+        body: str | dict | None = None,
+    ) -> Any:
+        return self.production.test_component(
+            self,
+            message=message,
+            classname=classname,
+            body=body,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        item: dict[str, Any] = {
+            "@Name": self.name,
+            "@Category": self.category,
+            "@ClassName": self.class_name,
+            "@PoolSize": _text_value(self.pool_size),
+            "@Enabled": _bool_text(self.enabled),
+            "@Foreground": _bool_text(self.foreground),
+            "@Comment": self.comment,
+            "@LogTraceEvents": _bool_text(self.log_trace_events),
+            "@Schedule": self.schedule,
+        }
+
+        settings = []
+        settings.extend(_settings_to_iris("Host", self.host_settings))
+        settings.extend(_settings_to_iris("Adapter", self.adapter_settings))
+        settings.extend(dict(setting) for setting in self.other_settings)
+        if settings:
+            item["Setting"] = settings
+
+        return item

iop/production/declarations.py

@@ -0,0 +1,190 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, ClassVar, Protocol
+
+from .common import SETTING_NAME_ALIASES
+from .types import TargetSetting
+
+
+class _NamedRouteTarget(Protocol):
+    @property
+    def name(self) -> str: ...
+
+
+@dataclass(frozen=True)
+class Route:
+    """Declarative route from a target setting to one or more targets."""
+
+    target_setting: str | TargetSetting
+    targets: str | _NamedRouteTarget | Iterable[str | _NamedRouteTarget]
+
+    @property
+    def target_setting_name(self) -> str:
+        return normalize_route_target_setting(self.target_setting)
+
+    @property
+    def target_setting_owner(self) -> type | None:
+        if isinstance(self.target_setting, TargetSetting):
+            return self.target_setting.owner
+        return None
+
+    @property
+    def target_names(self) -> tuple[str, ...]:
+        if _is_route_target(self.targets):
+            targets = (self.targets,)
+        else:
+            try:
+                targets = tuple(self.targets)
+            except TypeError as exc:
+                raise TypeError(
+                    f"Route {self.target_setting_name!r} targets must be an item name, "
+                    "a production item declaration, or an iterable of either"
+                ) from exc
+        if not targets:
+            raise ValueError(
+                f"Route {self.target_setting_name!r} requires at least one target"
+            )
+        return tuple(
+            _route_target_name(target, self.target_setting_name)
+            for target in targets
+        )
+
+
+@dataclass(frozen=True)
+class _ProductionItemDeclaration:
+    name: str
+    component: type | str | None = None
+    class_name: str | None = None
+    adapter_class: type | str | None = None
+    adapter_class_name: str | None = None
+    enabled: bool | str = True
+    pool_size: int | str = 1
+    category: str = ""
+    foreground: bool | str = False
+    comment: str = ""
+    log_trace_events: bool | str = False
+    schedule: str = ""
+    settings: Mapping[str, Any] | None = None
+    host_settings: Mapping[str, Any] | None = None
+    adapter_settings: Mapping[str, Any] | None = None
+    other_settings: Iterable[Mapping[str, Any]] | None = None
+    routes: Route | Iterable[Route] | None = field(default_factory=tuple)
+
+    kind: ClassVar[str] = "component"
+
+    @property
+    def host_setting_values(self) -> dict[str, Any]:
+        settings = _mapping(self.settings, "settings", self.name)
+        host_settings = _mapping(self.host_settings, "host_settings", self.name)
+        duplicates = sorted(settings.keys() & host_settings.keys())
+        if duplicates:
+            names = ", ".join(repr(name) for name in duplicates)
+            raise ValueError(
+                f"{self.kind.title()} item {self.name!r} declares duplicate "
+                f"Host setting keys: {names}"
+            )
+        merged = dict(settings)
+        merged.update(host_settings)
+        return merged
+
+    @property
+    def adapter_setting_values(self) -> dict[str, Any]:
+        return _mapping(self.adapter_settings, "adapter_settings", self.name)
+
+    @property
+    def other_setting_values(self) -> list[dict[str, Any]]:
+        return [dict(setting) for setting in self.other_settings or ()]
+
+    @property
+    def route_values(self) -> tuple[Route, ...]:
+        if self.routes is None:
+            return ()
+        if isinstance(self.routes, Route):
+            return (self.routes,)
+        routes = tuple(self.routes)
+        for route in routes:
+            if not isinstance(route, Route):
+                raise TypeError(
+                    f"{self.kind.title()} item {self.name!r} routes must be Route "
+                    f"instances"
+                )
+        return routes
+
+
+@dataclass(frozen=True)
+class ServiceItem(_ProductionItemDeclaration):
+    kind: ClassVar[str] = "service"
+
+
+@dataclass(frozen=True)
+class ComponentItem(_ProductionItemDeclaration):
+    kind: ClassVar[str] = "component"
+
+
+@dataclass(frozen=True)
+class ProcessItem(_ProductionItemDeclaration):
+    kind: ClassVar[str] = "process"
+
+
+@dataclass(frozen=True)
+class OperationItem(_ProductionItemDeclaration):
+    kind: ClassVar[str] = "operation"
+
+
+def normalize_route_target_setting(name: str | TargetSetting) -> str:
+    """Normalize known Pythonic route aliases without changing other settings."""
+
+    if isinstance(name, TargetSetting):
+        if not name.name:
+            raise ValueError(
+                "Route target setting must be declared on a component class"
+            )
+        return name.name
+    target_setting_name = str(name)
+    return SETTING_NAME_ALIASES.get(target_setting_name, target_setting_name)
+
+
+def normalize_route_target_setting_for_match(name: str | TargetSetting) -> str:
+    return normalize_route_target_setting(name)
+
+
+def _is_route_target(value: Any) -> bool:
+    return isinstance(value, str) or isinstance(value, _ProductionItemDeclaration)
+
+
+def _route_target_name(value: Any, target_setting_name: str) -> str:
+    if isinstance(value, str):
+        if value:
+            return value
+    elif isinstance(value, _ProductionItemDeclaration):
+        if value.name:
+            return value.name
+
+    raise TypeError(
+        f"Route {target_setting_name!r} targets must be item names or production item "
+        "declarations"
+    )
+
+
+def _mapping(
+    values: Mapping[str, Any] | None,
+    field_name: str,
+    item_name: str,
+) -> dict[str, Any]:
+    try:
+        return dict(values or {})
+    except (TypeError, ValueError) as exc:
+        raise TypeError(
+            f"Production item {item_name!r} {field_name} must be a mapping"
+        ) from exc
+
+
+__all__ = [
+    "ComponentItem",
+    "OperationItem",
+    "ProcessItem",
+    "Route",
+    "ServiceItem",
+]

iop/production/declarative.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, ClassVar, Protocol, cast
+
+from .component import ComponentRef
+from .declarations import (
+    Route,
+    _ProductionItemDeclaration,
+    normalize_route_target_setting_for_match,
+)
+from .types import TargetSettingRef
+
+
+class _ComponentFactory(Protocol):
+    def __call__(
+        self,
+        name_or_cls: str | type,
+        cls: type | None = None,
+        **kwargs: Any,
+    ) -> ComponentRef: ...
+
+
+class _DeclarativeProductionHost(Protocol):
+    def component(
+        self,
+        name_or_cls: str | type,
+        cls: type | None = None,
+        **kwargs: Any,
+    ) -> ComponentRef: ...
+
+    def service(
+        self,
+        name_or_cls: str | type,
+        cls: type | None = None,
+        **kwargs: Any,
+    ) -> ComponentRef: ...
+
+    def process(
+        self,
+        name_or_cls: str | type,
+        cls: type | None = None,
+        **kwargs: Any,
+    ) -> ComponentRef: ...
+
+    def operation(
+        self,
+        name_or_cls: str | type,
+        cls: type | None = None,
+        **kwargs: Any,
+    ) -> ComponentRef: ...
+
+    def item(self, name: str) -> ComponentRef: ...
+
+    def connect(
+        self,
+        source: TargetSettingRef,
+        target_component: ComponentRef | str | None = None,
+        *,
+        mode: str = "replace",
+    ) -> None: ...
+
+
+class _DeclarativeProductionMixin:
+    components: ClassVar[Iterable[_ProductionItemDeclaration] | None] = ()
+    services: ClassVar[Iterable[_ProductionItemDeclaration] | None] = ()
+    processes: ClassVar[Iterable[_ProductionItemDeclaration] | None] = ()
+    operations: ClassVar[Iterable[_ProductionItemDeclaration] | None] = ()
+
+    def _hydrate_declared_items(self) -> None:
+        declarations: list[_ProductionItemDeclaration] = []
+        for attr_name, expected_kind in (
+            ("components", "component"),
+            ("services", "service"),
+            ("processes", "process"),
+            ("operations", "operation"),
+        ):
+            for declaration in self._declared_items(attr_name):
+                if declaration.kind != expected_kind:
+                    raise TypeError(
+                        f"{attr_name} must contain {expected_kind.title()}Item "
+                        f"declarations"
+                    )
+                self._raise_declared_route_conflicts(declaration)
+                self._add_declared_item(declaration)
+                declarations.append(declaration)
+
+        for declaration in declarations:
+            self._connect_declared_routes(declaration)
+
+    def _declared_items(self, attr_name: str) -> tuple[_ProductionItemDeclaration, ...]:
+        values: object = getattr(type(self), attr_name, ())
+        if values is None:
+            return ()
+        if isinstance(values, _ProductionItemDeclaration):
+            return (values,)
+        try:
+            declarations = tuple(cast(Iterable[object], values))
+        except TypeError as exc:
+            raise TypeError(f"{attr_name} must be an iterable of item declarations") from exc
+        items: list[_ProductionItemDeclaration] = []
+        for declaration in declarations:
+            if not isinstance(declaration, _ProductionItemDeclaration):
+                raise TypeError(f"{attr_name} must contain production item declarations")
+            items.append(declaration)
+        return tuple(items)
+
+    def _raise_declared_route_conflicts(
+        self,
+        declaration: _ProductionItemDeclaration,
+    ) -> None:
+        host_target_settings = {
+            normalize_route_target_setting_for_match(name)
+            for name in declaration.host_setting_values
+        }
+        route_target_settings = {
+            route.target_setting_name for route in declaration.route_values
+        }
+        conflicts = sorted(host_target_settings & route_target_settings)
+        if not conflicts:
+            return
+        names = ", ".join(repr(name) for name in conflicts)
+        raise ValueError(
+            f"{declaration.kind.title()} item {declaration.name!r} declares route "
+            "target setting(s) in Host settings: "
+            f"{names}. Declare route target settings with Route only."
+        )
+
+    def _add_declared_item(self, declaration: _ProductionItemDeclaration) -> None:
+        kwargs: dict[str, Any] = {
+            "enabled": declaration.enabled,
+            "pool_size": declaration.pool_size,
+            "category": declaration.category,
+            "foreground": declaration.foreground,
+            "comment": declaration.comment,
+            "log_trace_events": declaration.log_trace_events,
+            "schedule": declaration.schedule,
+            "settings": declaration.host_setting_values,
+            "adapter_settings": declaration.adapter_setting_values,
+        }
+        if declaration.adapter_class is not None:
+            kwargs["adapter_class"] = declaration.adapter_class
+        if declaration.adapter_class_name is not None:
+            kwargs["adapter_class_name"] = declaration.adapter_class_name
+
+        host = cast(_DeclarativeProductionHost, self)
+        methods: dict[str, _ComponentFactory] = {
+            "component": host.component,
+            "service": host.service,
+            "process": host.process,
+            "operation": host.operation,
+        }
+        method = methods[declaration.kind]
+
+        component = declaration.component
+        if isinstance(component, type):
+            if declaration.class_name is not None:
+                kwargs["class_name"] = declaration.class_name
+            ref = method(declaration.name, component, **kwargs)
+            ref.other_settings = declaration.other_setting_values
+            return
+
+        class_name = declaration.class_name
+        if component is not None:
+            component_class_name = str(component)
+            if class_name is not None and class_name != component_class_name:
+                raise ValueError(
+                    f"{declaration.kind.title()} item {declaration.name!r} "
+                    "declares conflicting component and class_name values"
+                )
+            class_name = component_class_name
+
+        if class_name is None:
+            raise ValueError(
+                f"{declaration.kind.title()} item {declaration.name!r} requires "
+                "a component class or class_name"
+            )
+        kwargs["class_name"] = class_name
+        ref = method(declaration.name, **kwargs)
+        ref.other_settings = declaration.other_setting_values
+
+    def _connect_declared_routes(self, declaration: _ProductionItemDeclaration) -> None:
+        host = cast(_DeclarativeProductionHost, self)
+        source = host.item(declaration.name)
+        for route in declaration.route_values:
+            self._raise_if_route_target_setting_owner_mismatch(source, route)
+            target_setting_ref = source.target_setting(route.target_setting_name)
+            targets = route.target_names
+            host.connect(target_setting_ref, targets[0])
+            for target in targets[1:]:
+                host.connect(
+                    target_setting_ref,
+                    target,
+                    mode="add",
+                )
+
+    def _raise_if_route_target_setting_owner_mismatch(
+        self,
+        source: ComponentRef,
+        route: Route,
+    ) -> None:
+        owner = route.target_setting_owner
+        if (
+            owner is None
+            or source.component_class is None
+            or issubclass(source.component_class, owner)
+        ):
+            return
+        raise ValueError(
+            f"Route target setting {route.target_setting_name!r} belongs to "
+            f"{owner.__module__}.{owner.__qualname__}, not "
+            f"{source.component_class.__module__}."
+            f"{source.component_class.__qualname__}"
+        )