systempy 0.1.0__tar.gz

systempy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Anton Kovalevich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

systempy-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: systempy
+Version: 0.1.0
+Summary: Python application component initialization system
+Home-page: https://github.com/kai3341/systemPY
+Author: kai3341
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions
+Provides-Extra: extra
+Requires-Dist: celery>=5.5.1; extra == "extra"
+Requires-Dist: ptpython>=3.0.30; extra == "extra"
+Requires-Dist: starlette>=0.46.2; extra == "extra"
+Dynamic: home-page
+Dynamic: license-file
+
+# systemPY
+
+![Logo](https://raw.githubusercontent.com/kai3341/systemPY/main/docs/images/systempy-logo.png)
+
+Python application component initialization system
+
+![python](https://img.shields.io/pypi/pyversions/systemPY)
+![version](https://img.shields.io/pypi/v/systemPY)
+![downloads](https://img.shields.io/pypi/dm/systemPY)
+![format](https://img.shields.io/pypi/format/systemPY)
+[![Documentation Status](https://readthedocs.org/projects/systempy/badge/?version=latest)](https://systempy.readthedocs.io/en/latest/?badge=latest)
+![GitHub issues](https://img.shields.io/github/issues/kai3341/systemPY)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+
+Full documantation is available at
+[Read the Docs](https://systempy.readthedocs.io/en/latest/)
+
+## The problem
+
+The regular application contain many atomic components. Asyncio makes theirs
+initializing a little bit complicated. It's OK, when you have single entrypoint
+and initialize your application components via your framework. While you add
+new components to your application iteratively, you don't see any problem
+
+When you create any new entrypoint, you have to think a lot, how to initialize
+application components again, which callbacks should be called and in which
+order. But it's a half of the problem! You have to implement also graceful
+shutdown
+
+The most painful part is one-time scripts. It's kind of The Banana Gorilla
+Problem: you wanted a banana but you have to initialize a gorilla holding the
+banana and the entire jungle, and then graceful shutdown it
+
+## Solution
+
+This library allows you to implement application startup and shutdown in
+declarative way. You have to implement a class for each your component,
+write the startup and shutdown code. Then combine required components as
+mixins into the current application `Unit` class. Then create an instance
+and pass dependencies as keyword arguments. In case it's daemon run
+`instance.run_sync()` methed
+
+## Basic principles
+
+There are 6 most significant stages of the application lifecycle:
+
+- `on_init` executes exactly once on application startup
+
+- `pre_startup` is called before event loop startup
+
+- `on_startup` is called exactly when event loop started
+
+- `on_shutdown` is called when application is going shutdown or reload but
+  event loop still working
+
+- `post_shutdown` is called after event loop stopped or drained. When
+  application is going to reload, then it should be called `pre_startup`
+
+- `on_exit` executes exactly once when application is stopping
+
+You may to create `Unit` classes for each your application component where you
+may put your code. Then you may combine these `Unit` class mixins into the
+current worker class, which aggregate your defined callbacks and run in the
+right order. Depending on application type, these callbacks may be called by
+primary application or by you are

systempy-0.1.0/README.md

@@ -0,0 +1,66 @@
+# systemPY
+
+![Logo](https://raw.githubusercontent.com/kai3341/systemPY/main/docs/images/systempy-logo.png)
+
+Python application component initialization system
+
+![python](https://img.shields.io/pypi/pyversions/systemPY)
+![version](https://img.shields.io/pypi/v/systemPY)
+![downloads](https://img.shields.io/pypi/dm/systemPY)
+![format](https://img.shields.io/pypi/format/systemPY)
+[![Documentation Status](https://readthedocs.org/projects/systempy/badge/?version=latest)](https://systempy.readthedocs.io/en/latest/?badge=latest)
+![GitHub issues](https://img.shields.io/github/issues/kai3341/systemPY)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+
+Full documantation is available at
+[Read the Docs](https://systempy.readthedocs.io/en/latest/)
+
+## The problem
+
+The regular application contain many atomic components. Asyncio makes theirs
+initializing a little bit complicated. It's OK, when you have single entrypoint
+and initialize your application components via your framework. While you add
+new components to your application iteratively, you don't see any problem
+
+When you create any new entrypoint, you have to think a lot, how to initialize
+application components again, which callbacks should be called and in which
+order. But it's a half of the problem! You have to implement also graceful
+shutdown
+
+The most painful part is one-time scripts. It's kind of The Banana Gorilla
+Problem: you wanted a banana but you have to initialize a gorilla holding the
+banana and the entire jungle, and then graceful shutdown it
+
+## Solution
+
+This library allows you to implement application startup and shutdown in
+declarative way. You have to implement a class for each your component,
+write the startup and shutdown code. Then combine required components as
+mixins into the current application `Unit` class. Then create an instance
+and pass dependencies as keyword arguments. In case it's daemon run
+`instance.run_sync()` methed
+
+## Basic principles
+
+There are 6 most significant stages of the application lifecycle:
+
+- `on_init` executes exactly once on application startup
+
+- `pre_startup` is called before event loop startup
+
+- `on_startup` is called exactly when event loop started
+
+- `on_shutdown` is called when application is going shutdown or reload but
+  event loop still working
+
+- `post_shutdown` is called after event loop stopped or drained. When
+  application is going to reload, then it should be called `pre_startup`
+
+- `on_exit` executes exactly once when application is stopping
+
+You may to create `Unit` classes for each your application component where you
+may put your code. Then you may combine these `Unit` class mixins into the
+current worker class, which aggregate your defined callbacks and run in the
+right order. Depending on application type, these callbacks may be called by
+primary application or by you are

systempy-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "systempy"
+version = "0.1.0"
+description = "Python application component initialization system"
+authors = [{name = "kai3341"}]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "typing-extensions",
+]
+
+[project.optional-dependencies]
+extra = [
+    "celery>=5.5.1",
+    "ptpython>=3.0.30",
+    "starlette>=0.46.2",
+]
+
+[tool.pyright]
+include = ["systempy/", "tests/", "_util/"]
+reportMissingModuleSource = false
+reportArgumentType = false
+reportCallIssue = false
+reportAssignmentType = false
+reportGeneralTypeIssues = false
+reportIndexIssue = false
+reportInvalidTypeArguments = false
+reportIncompatibleMethodOverride = false
+
+[tool.ruff.lint]
+select=["ALL"]
+ignore = ["D", "S101", "TID252", "ANN401", "PTH119", "RET503", "PT009"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["INP001", "E402", "C901"]
+"examples/*" = ["INP001", "E402"]
+"_util/*" = ["E402"]
+
+[tool.mypy]
+python_version = "3.11"
+mypy_path = "$MYPY_CONFIG_FILE_DIR/systempy"
+disable_error_code = ["import-untyped", "return", "empty-body"]
+exclude = ["^build/", "^dist/"]
+
+[dependency-groups]
+dev = [
+    "mkdocs-material>=9.6.11",
+    "mypy[mypyc]>=1.15.0",
+    "ruff>=0.11.5",
+]

systempy-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

systempy-0.1.0/setup.py

@@ -0,0 +1,96 @@
+from os import getenv
+
+from setuptools import setup
+
+from setup_constants import DESCRIPTION, NAME, NAME_CANONICAL, VERSION
+
+if getenv("USE_MYPYC") == "1":
+    from setup_mypycify import ext_modules
+else:
+    ext_modules = []
+
+
+requirements: list[str] = []
+
+requirements_build: list[str] = []
+
+packages = [
+    NAME,
+    f"{NAME}.libsystempy",
+    f"{NAME}.unit",
+    f"{NAME}.unit.ext",
+    f"{NAME}.unit.repl",
+]
+
+package_data = {
+    NAME: ["py.typed"],
+}
+
+keywords = [
+    "asyncio",
+    "graceful",
+    "init",
+    "initialization",
+    "shutdown",
+    "manager",
+]
+
+classifiers__python_versions = (
+    "3 :: Only",
+    "3.9",
+    "3.10",
+    "3.11",
+    "3.12",
+    "3.13",
+    "3.14",
+)
+
+classifiers__programming_language = tuple(
+    f"Programming Language :: Python :: {i}"
+    # ===
+    for i in classifiers__python_versions
+)
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    *classifiers__programming_language,
+    # Topic
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    # Typing
+    "Typing :: Typed",
+]
+
+py_modules = [
+    NAME,
+    # "setup_constants",
+]
+
+with open("README.md", encoding="utf-8") as readme_file:  # noqa: PTH123
+    long_description = readme_file.read()
+
+
+setup(
+    classifiers=classifiers,
+    description=DESCRIPTION,
+    install_requires=requirements,
+    extras_require={
+        "dev": requirements_build,
+    },
+    license="MIT",
+    packages=packages,
+    package_data=package_data,
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    include_package_data=True,
+    keywords=keywords,
+    name=NAME_CANONICAL,
+    py_modules=py_modules,
+    ext_modules=ext_modules,
+    url="https://github.com/kai3341/systemPY",
+    version=VERSION,
+    zip_safe=True,
+)

systempy-0.1.0/systempy/__init__.py

@@ -0,0 +1,35 @@
+from .libsystempy import (
+    DIRECTION,
+    ROLE,
+    register_hook_after,
+    register_hook_before,
+    register_target_method,
+)
+from .target import AsyncMixinABC, SyncMixinABC, Target
+from .unit import (
+    AsyncScriptUnit,
+    DaemonUnit,
+    EventWaitUnit,
+    LoopUnit,
+    ReplUnit,
+    ScriptUnit,
+    Unit,
+)
+
+__all__ = (
+    "DIRECTION",
+    "ROLE",
+    "AsyncMixinABC",
+    "AsyncScriptUnit",
+    "DaemonUnit",
+    "EventWaitUnit",
+    "LoopUnit",
+    "ReplUnit",
+    "ScriptUnit",
+    "SyncMixinABC",
+    "Target",
+    "Unit",
+    "register_hook_after",
+    "register_hook_before",
+    "register_target_method",
+)

systempy-0.1.0/systempy/libsystempy/__init__.py

@@ -0,0 +1,20 @@
+from .constants import handler_metadata
+from .enums import DIRECTION, ROLE
+from .register import (
+    mark_as_target,
+    register_hook_after,
+    register_hook_before,
+    register_target,
+    register_target_method,
+)
+
+__all__ = (
+    "DIRECTION",
+    "ROLE",
+    "handler_metadata",
+    "mark_as_target",
+    "register_hook_after",
+    "register_hook_before",
+    "register_target",
+    "register_target_method",
+)

systempy-0.1.0/systempy/libsystempy/callback_plan.py

@@ -0,0 +1,60 @@
+from collections.abc import Callable, Generator, Iterable
+
+from .check import check_callback_signature
+from .constants import lifecycle_registered_methods
+from .hook_registry import HookRegistry
+from .local_typing import P, R, WeakTypeIterable
+from .register import register_hook_after, register_hook_before
+
+
+def build_callback_plan_hook_iter(
+    cls: type,
+    bases: WeakTypeIterable,
+    reason: Callable[P, R],
+    hook_registry: HookRegistry[P, R],
+) -> Generator[Callable[P, R], None, None]:
+    if reason in hook_registry:
+        next_reasons = hook_registry[reason]
+        for next_reason in next_reasons:
+            assert callable(next_reason)
+            next_registered_methods = lifecycle_registered_methods[next_reason]
+            next_reason_interface = next_registered_methods.interface()
+            direction_handler = next_registered_methods.direction
+            assert next_reason_interface
+
+            if issubclass(cls, next_reason_interface):
+                next_callbacks = direction_handler(bases, next_reason)
+
+                for next_callback in next_callbacks:
+                    check_callback_signature(next_reason, next_callback)
+
+                yield from build_callback_plan_iter(
+                    cls,
+                    bases,
+                    next_reason,
+                    next_callbacks,
+                )
+
+
+def build_callback_plan_iter(
+    cls: type,
+    bases: WeakTypeIterable,
+    reason: Callable[P, R],
+    callbacks: Iterable[Callable[P, R]] = (),
+) -> Generator[Callable[P, R], None, None]:
+    yield from build_callback_plan_hook_iter(cls, bases, reason, register_hook_before)
+    yield from callbacks
+    yield from build_callback_plan_hook_iter(cls, bases, reason, register_hook_after)
+
+
+def build_callback_plan(
+    cls: type,
+    bases: WeakTypeIterable,
+    reason: Callable[P, R],
+    callbacks: Iterable[Callable[P, R]],
+) -> tuple[Callable[P, R], ...]:
+    for func in callbacks:
+        check_callback_signature(reason, func)
+
+    callbacks_total = build_callback_plan_iter(cls, bases, reason, callbacks)
+    return tuple(callbacks_total)

systempy-0.1.0/systempy/libsystempy/check.py

@@ -0,0 +1,52 @@
+from collections.abc import Callable
+from inspect import iscoroutinefunction
+
+from .constants import sync_or_async
+from .enums import DIRECTION
+from .local_typing import function_types
+from .register import register_check_method_type
+
+sync_or_async_names = tuple(i.value for i in sync_or_async)
+sync_or_async_names_rev = tuple(reversed(sync_or_async_names))
+
+CHECK_CALLBACK_ERROR_MESSAGE__TEMPLATE = (
+    "{name} must be %sronous function, but {func} is %sronous"
+)
+
+check_callback_signature__error_message: tuple[str, ...] = (
+    CHECK_CALLBACK_ERROR_MESSAGE__TEMPLATE % sync_or_async_names,
+    CHECK_CALLBACK_ERROR_MESSAGE__TEMPLATE % sync_or_async_names_rev,
+)
+
+
+def check_callback_signature(reason: Callable, func: Callable) -> None:
+    """
+    When `reason` is syncronous, `func` have to be syncronous too
+    Asyncronous `reason` executors may to execute both `func` types
+    """
+
+    assert isinstance(reason, function_types)
+    assert isinstance(func, function_types)
+
+    reason_async = iscoroutinefunction(reason)
+    if reason_async:
+        return
+
+    if not iscoroutinefunction(func):
+        return
+
+    template = check_callback_signature__error_message[reason_async]
+
+    error_message = template.format(
+        name=reason.__name__,
+        func=func,
+    )
+
+    raise ValueError(error_message)
+
+
+@register_check_method_type(DIRECTION.GATHER)
+def gather(target: Callable) -> None:
+    if not iscoroutinefunction(target):
+        error_message = "Can not `asyncio.gather` syncronous method"
+        raise ValueError(error_message, target)

systempy-0.1.0/systempy/libsystempy/class_role.py

@@ -0,0 +1,32 @@
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Generic, NamedTuple, TypeVar
+from typing import final as typing_final
+
+from .configuration import apply_additional_configuration
+from .register import mark_as_final, mark_as_target, register_target
+
+T = TypeVar("T")
+
+
+class ClassRole(NamedTuple, Generic[T]):
+    app: Callable[[T], T]
+    unit: Callable[[T], T]
+    mixin: Callable[[T], T]
+    target: Callable[[T], T]
+
+
+default_dataclass_kwargs: dict[str, bool] = {
+    "kw_only": True,
+}
+
+nonfinal = dataclass(**default_dataclass_kwargs, init=False, repr=False, eq=False)
+final = dataclass(**default_dataclass_kwargs)
+
+
+class_role = ClassRole[type](
+    lambda cls: final(apply_additional_configuration(mark_as_final(typing_final(cls)))),
+    nonfinal,
+    lambda cls: nonfinal(mark_as_target(cls)),
+    lambda cls: nonfinal(register_target(cls)),
+)

systempy-0.1.0/systempy/libsystempy/configuration.py

@@ -0,0 +1,56 @@
+from dataclasses import fields
+from typing import Any
+
+from .constants import lifecycle_additional_configuration
+from .creation import create_partial_handler_generic
+from .local_dataclasses import ClsCFG
+from .local_typing import WeakTypeIterable
+from .misc import get_key_or_create
+from .register import register_addition_cfg_applier
+
+
+@register_addition_cfg_applier
+def stack_method(cls: type, config: ClsCFG) -> None:
+    sm_cfg = config.stack_method
+    create = create_partial_handler_generic(cls)
+
+    for stage_config in sm_cfg.values():
+        create(stage_config)
+
+
+def apply_additional_config(cls: type, config: ClsCFG) -> None:
+    for clscfg_field in fields(config):
+        key = clscfg_field.name
+        apply_cfg_handler = register_addition_cfg_applier[key]
+        apply_cfg_handler(cls, config)
+
+
+def apply_additional_configuration(this_cls: type) -> type:
+    for cls, config in lifecycle_additional_configuration.items():
+        if issubclass(this_cls, cls):
+            apply_additional_config(this_cls, config)
+    return this_cls
+
+
+def update_annotation(
+    clsdict: dict[str, Any],
+    bases: WeakTypeIterable,
+) -> None:
+    annotations: dict[str, type] = get_key_or_create(
+        clsdict,
+        "__annotations__",
+        dict,
+    )
+
+    for base in bases:
+        basedict = vars(base)
+
+        if "__annotations__" not in basedict:
+            continue
+
+        target_annotations: dict[str, type] = basedict["__annotations__"]
+        annotations.update(target_annotations)
+
+        for key in target_annotations:
+            if key in basedict:
+                clsdict[key] = basedict[key]

systempy-0.1.0/systempy/libsystempy/constants.py

@@ -0,0 +1,16 @@
+from weakref import WeakKeyDictionary
+
+from .enums import TYPE as _TYPE
+from .local_typing import DisallowedAttrInfo, LFMetadata, LFRegistered, LFTypeConfig
+
+lifecycle_additional_configuration: LFTypeConfig[type] = WeakKeyDictionary()
+lifecycle_registered_methods: LFRegistered = WeakKeyDictionary()
+
+sync_or_async = (_TYPE.SYNC, _TYPE.ASYNC)
+handler_metadata: LFMetadata = WeakKeyDictionary()
+
+
+lifecycle_disallowed_attrs: list[DisallowedAttrInfo] = [
+    ("__init__", "Use `on_init` instead"),
+    ("__post_init__", "Use `on_init` instead"),
+]

systempy-0.1.0/systempy/libsystempy/creation.py

@@ -0,0 +1,32 @@
+from collections.abc import Callable
+from functools import partial
+from weakref import ref
+
+from . import extraction
+from .local_dataclasses import GenericHandlerSettings
+from .local_typing import WeakTypeIterable
+
+
+def create_handler_generic(
+    cls_ref: ref[type],
+    bases: WeakTypeIterable,
+    settings: GenericHandlerSettings,
+) -> None:
+    collect = settings.collect()
+    reason = settings.reason()
+    compose = settings.compose()
+    cls = cls_ref()
+    assert collect
+    assert reason
+    assert compose
+    assert cls
+    callbacks = collect(bases, reason)
+    handler = compose(cls, bases, reason, callbacks)
+    setattr(cls, reason.__name__, handler)
+
+
+def create_partial_handler_generic(
+    cls: type,
+) -> Callable[[GenericHandlerSettings], None]:
+    bases = extraction.extract_bases(cls)
+    return partial(create_handler_generic, ref(cls), bases)

systempy-0.1.0/systempy/libsystempy/enums.py

@@ -0,0 +1,30 @@
+from enum import Enum, unique
+
+
+@unique
+class DIRECTION(str, Enum):
+    """
+    Public enum containing supported directions. Rely on your IDE's help
+    """
+
+    FORWARD = "forward"
+    BACKWARD = "backward"
+    GATHER = "gather"
+
+
+@unique
+class TYPE(str, Enum):
+    """
+    Private internal enum
+    """
+
+    SYNC = "sync"
+    ASYNC = "async"
+
+
+@unique
+class ROLE(str, Enum):
+    APP = "app"
+    UNIT = "unit"
+    MIXIN = "mixin"
+    TARGET = "target"