aiobp 0.1.0__tar.gz

aiobp-0.1.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2024 INSOFT s.r.o.
+
+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.

aiobp-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.1
+Name: aiobp
+Version: 0.1.0
+Summary: Boilerplate for asyncio service
+Author: INSOFT s.r.o.
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Description-Content-Type: text/markdown
+
+Boilerplate for asyncio service
+===============================
+
+This module provides boilerplate for microservices written in asyncio:
+
+  * Runner with task reference handler and graceful shutdown
+  * Configuration provider
+  * Logger with color support
+
+```python
+import asyncio
+
+from aiobp import runner
+
+async def main():
+    try:
+        await asyncio.sleep(60)
+    except asyncio.CancelledError:
+        print('Saving data...')
+
+runner(main())
+```
+
+
+More complex example
+--------------------
+
+```python
+import asyncio
+import aiohttp  # just for example
+import sys
+
+from aiobp import create_task, on_shutdown, runner
+from aiobp.config import InvalidConfigFile, sys_argv_or_filenames
+from aiobp.config.conf import loader
+from aiobp.logging import LoggingConfig, add_devel_log_level, log, setup_logging
+
+
+class WorkerConfig:
+    """Your microservice worker configuration"""
+
+    sleep: int = 5
+
+
+class Config:
+    """Put configurations together"""
+
+    worker: WorkerConfig
+    log: LoggingConfig
+
+
+async def worker(config: WorkerConfig, client_session: aiohttp.ClientSession) -> int:
+    """Perform service work"""
+    attempts = 0
+    try:
+        async with client_session.get('http://python.org') as resp:
+            assert resp.status == 200
+            log.debug('Page length %d', len(await resp.text()))
+            attempts += 1
+        await asyncio.sleep(config.sleep)
+    except asyncio.CancelledError:
+        log.info('Doing some shutdown work')
+        await client_session.post('http://localhost/service/attempts', data={'attempts': attempts})
+
+    return attempts
+
+
+async def service(config: Config):
+    """Your microservice"""
+    client_session = aiohttp.ClientSession()
+    on_shutdown(client_session.close, after_tasks_cancel=True)
+
+    create_task(worker(config.worker, client_session), 'PythonFetcher')
+
+    # you can do some monitoring, statistics collection, etc.
+    # or just let the method finish and the runner will wait for Ctrl+C or kill
+
+
+def main():
+    """Example microservice"""
+    add_devel_log_level()
+    try:
+        config_filename = sys_argv_or_filenames('service.local.conf', 'service.conf')
+        config = loader(config_filename, Config)
+    except InvalidConfigFile as error:
+        print(f'Invalid configuration: {error}')
+        sys.exit(1)
+
+    setup_logging(config.log)
+    log.info("Using config file: %s", config_filename)
+
+    runner(service(config))
+
+
+if __name__ == '__main__':
+    main()
+```
+

aiobp-0.1.0/README.md

@@ -0,0 +1,97 @@
+Boilerplate for asyncio service
+===============================
+
+This module provides boilerplate for microservices written in asyncio:
+
+  * Runner with task reference handler and graceful shutdown
+  * Configuration provider
+  * Logger with color support
+
+```python
+import asyncio
+
+from aiobp import runner
+
+async def main():
+    try:
+        await asyncio.sleep(60)
+    except asyncio.CancelledError:
+        print('Saving data...')
+
+runner(main())
+```
+
+
+More complex example
+--------------------
+
+```python
+import asyncio
+import aiohttp  # just for example
+import sys
+
+from aiobp import create_task, on_shutdown, runner
+from aiobp.config import InvalidConfigFile, sys_argv_or_filenames
+from aiobp.config.conf import loader
+from aiobp.logging import LoggingConfig, add_devel_log_level, log, setup_logging
+
+
+class WorkerConfig:
+    """Your microservice worker configuration"""
+
+    sleep: int = 5
+
+
+class Config:
+    """Put configurations together"""
+
+    worker: WorkerConfig
+    log: LoggingConfig
+
+
+async def worker(config: WorkerConfig, client_session: aiohttp.ClientSession) -> int:
+    """Perform service work"""
+    attempts = 0
+    try:
+        async with client_session.get('http://python.org') as resp:
+            assert resp.status == 200
+            log.debug('Page length %d', len(await resp.text()))
+            attempts += 1
+        await asyncio.sleep(config.sleep)
+    except asyncio.CancelledError:
+        log.info('Doing some shutdown work')
+        await client_session.post('http://localhost/service/attempts', data={'attempts': attempts})
+
+    return attempts
+
+
+async def service(config: Config):
+    """Your microservice"""
+    client_session = aiohttp.ClientSession()
+    on_shutdown(client_session.close, after_tasks_cancel=True)
+
+    create_task(worker(config.worker, client_session), 'PythonFetcher')
+
+    # you can do some monitoring, statistics collection, etc.
+    # or just let the method finish and the runner will wait for Ctrl+C or kill
+
+
+def main():
+    """Example microservice"""
+    add_devel_log_level()
+    try:
+        config_filename = sys_argv_or_filenames('service.local.conf', 'service.conf')
+        config = loader(config_filename, Config)
+    except InvalidConfigFile as error:
+        print(f'Invalid configuration: {error}')
+        sys.exit(1)
+
+    setup_logging(config.log)
+    log.info("Using config file: %s", config_filename)
+
+    runner(service(config))
+
+
+if __name__ == '__main__':
+    main()
+```

aiobp-0.1.0/aiobp/__init__.py

@@ -0,0 +1,7 @@
+__version__ = '0.1.0'
+
+from .logging import log
+from .runner import runner, on_shutdown
+from .task import create_task
+
+__all__ = ["create_task", "log", "on_shutdown", "runner"]

aiobp-0.1.0/aiobp/config/__init__.py

@@ -0,0 +1,27 @@
+"""Service configuration"""
+
+import os
+import sys
+
+from .exceptions import InvalidConfigFile
+
+
+def sys_argv_or_filenames(*filenames: str) -> str:
+    """Return usable configuration filename"""
+    if len(sys.argv) == 2:
+        filename = sys.argv[1]
+        if not os.path.isfile(filename):
+            raise InvalidConfigFile(f'Provided filename "{filename}" not found')
+
+        return filename
+
+    for filename in filenames:
+        if not os.path.isfile(filename):
+            continue
+
+        return filename
+
+    raise InvalidConfigFile(f'None of default filenames found: {", ".join(filenames)}')
+
+
+__all__ = ["InvalidConfigFile", "sys_argv_or_filenames"]

aiobp-0.1.0/aiobp/config/annotations.py

@@ -0,0 +1,116 @@
+"""Configuration structure from class annotations
+
+Given config:
+
+class ServiceConfig:
+    host: str
+    port: int = 8080
+
+
+class LogConfig:
+    level: str = "DEBUG"
+    filename: str
+
+
+class Config:
+    service: ServiceConfig
+    log: LogConfig
+
+
+Method get_options inspects classes recursively and return configuration map as
+nested dicts of options/attributes (keys) having type and default value (vals):
+
+config_map = get_options(Config)
+{
+    # module name
+    "service": {
+        # option name: type, default value or AttributeError if default is not provided
+        "host": (str, AttributeError),
+        "port": (int, 8080),
+    },
+    "log": {
+        "level": (str, "DEBUG"),
+        "filename": (str, AttributeError),
+    },
+}
+
+
+Loader class constructor will use configuration map, fill values from configuration
+file (override default values) and use set_options method to make instances of nested
+configuration classes:
+
+
+class Loader:
+    def __init__(self, filename):
+        config_map = get_options(Config)
+
+        # parse filename and fill values
+
+        set_options(self, config_map)
+
+
+Finally what we need to use in our microservice:
+
+config = Config(Loader('some.file'))
+"""
+
+from collections import namedtuple
+from typing import Annotated, Optional, Type, Union, get_type_hints
+
+from .exceptions import InvalidConfigFile, InvalidConfigImplementation
+
+
+ConfigOption = namedtuple('Option', ['type', 'value'])
+
+
+ConfigMap = dict[str, Union['ConfigMap', ConfigOption]]
+
+
+CONFIG_TYPES = (
+    bool,
+    float,
+    int,
+    str,
+    Optional[bool],
+    Optional[float],
+    Optional[int],
+    Optional[str],
+)
+
+
+def get_options(config_class: Type[Annotated]) -> ConfigMap:
+    """Extract configuration map recursively"""
+    config: ConfigMap = {}
+
+    options = get_type_hints(config_class)
+    if not options:
+        raise InvalidConfigImplementation(f'Configuration class "{config_class}" has no configuration options')
+
+    for option_name, option_type in options.items():
+        if option_type not in CONFIG_TYPES:
+            config[option_name] = get_options(option_type)
+            continue
+
+        try:
+            default_value = getattr(config_class, option_name)
+        except AttributeError as error:
+            default_value = error
+        config[option_name] = ConfigOption(option_type, default_value)
+
+    return config
+
+
+def set_options(config: Annotated, values: ConfigMap, path: Optional[list[str]] = None) -> Annotated:
+    """Make instances of configuration classes and set values"""
+    for option_name, option_type in get_type_hints(config).items():
+        if option_type not in CONFIG_TYPES:
+            path = [option_name] if path is None else [*path, option_name]
+            value = set_options(option_type(), values.get(option_name), path)
+        else:
+            value = values.get(option_name)
+            if isinstance(value, Exception):
+                raise InvalidConfigFile(f'missing option "{option_name}" in section "{".".join(path)}"') from value
+
+        setattr(config, option_name, value)
+
+    return config

aiobp-0.1.0/aiobp/config/conf.py

@@ -0,0 +1,37 @@
+"""INI like configuration loader"""
+
+import configparser
+
+from typing import Annotated, Type
+
+from .annotations import ConfigOption, get_options, set_options
+from .exceptions import InvalidConfigImplementation
+
+
+def loader(filename: str, config_class: Type[Annotated]) -> Annotated:
+    """INI like configuration loader"""
+    conf = configparser.ConfigParser()
+    conf.read(filename)
+
+    config = get_options(config_class)
+
+    for section_name, options in config.items():
+        if not isinstance(options, dict):
+            raise InvalidConfigImplementation(f'Class "{config_class.__name__}" can\'t have direct option "{section_name}"')
+
+        for option_name, option in options.items():
+            if not isinstance(option, ConfigOption):
+                raise InvalidConfigImplementation(f'"{section_name}" can have only scalar attributes, not subsection "{option_name}"')
+
+            if isinstance(option.type, int):
+                get = conf.getint
+            elif isinstance(option.type, float):
+                get = conf.getfloat
+            elif isinstance(option.type, bool):
+                get = conf.getboolean
+            else:
+                get = conf.get
+
+            options[option_name] = get(section_name, option_name, fallback=option.value)
+
+    return set_options(config_class(), config)

aiobp-0.1.0/aiobp/config/exceptions.py

@@ -0,0 +1,10 @@
+"""Configration exceptions"""
+
+class InvalidConfigFile(BaseException):
+    """Invalid configuration file"""
+
+
+class InvalidConfigImplementation(BaseException):
+    """Invalid usage of annotations for configuration"""
+    # you shouldn't catch this exception
+    # it indicates invalid code, not invalid configuration file itself

aiobp-0.1.0/aiobp/config/json.py

@@ -0,0 +1,36 @@
+"""Load configuration from JSON file"""
+
+import json
+
+from typing import Annotated, Type
+
+from .exceptions import InvalidConfigFile
+from .annotations import get_options, set_options
+
+
+def loader(filename: str, config_class: Type[Annotated]) -> Annotated:
+    """Load configuration from JSON file"""
+    with open(filename, 'r', encoding='ascii') as fp:
+        conf = json.load(fp)
+
+    if not isinstance(conf, dict):
+        # TODO: add unlimited depth support
+        raise InvalidConfigFile('JSON configuration structure must be dict[str, dict[str, any]]')
+
+    config = get_options(config_class)
+
+    for module_name, options in config.items():
+        module_conf = config.get(module_name, {})
+        for option_name, (option_type, default_value) in options.items():
+            try:
+                value = option_type(module_conf[option_name])
+            except KeyError:
+                value = default_value
+            except Exception as error:
+                value = error
+
+            options[option_name] = value
+
+    config_instance = config_class()
+    set_options(config_instance, config)
+    return config_instance

aiobp-0.1.0/aiobp/config/loader/conf.py

@@ -0,0 +1,39 @@
+"""INI like configuration loader"""
+
+import configparser
+
+from typing import Annotated, Type
+
+from ..annotations import ConfigOption, get_options, set_options
+from ..exceptions import InvalidConfigImplementation
+
+
+def loader(filename: str, config_class: Type[Annotated]) -> Annotated:
+    """INI like configuration loader"""
+    conf = configparser.ConfigParser()
+    conf.read(filename)
+
+    config = get_options(config_class)
+
+    for section_name, options in config.items():
+        if not isinstance(options, dict):
+            raise InvalidConfigImplementation(f'Class "{config_class.__name__}" can\'t have direct option "{section_name}"')
+
+        for option_name, option in options.items():
+            if not isinstance(option, ConfigOption):
+                raise InvalidConfigImplementation(f'"{section_name}" can have only scalar attributes, not subsection "{option_name}"')
+
+            if isinstance(option.type, int):
+                get = conf.getint
+            elif isinstance(option.type, float):
+                get = conf.getfloat
+            elif isinstance(option.type, bool):
+                get = conf.getboolean
+            else:
+                get = conf.get
+
+            options[option_name] = get(section_name, option_name, fallback=option.value)
+
+    config_instance = config_class()
+    set_options(config_instance, config)
+    return config_instance

aiobp-0.1.0/aiobp/config/loader/json.py

@@ -0,0 +1,36 @@
+"""Load configuration from JSON file"""
+
+import json
+
+from typing import Annotated, Type
+
+from ..exceptions import InvalidConfigFile
+from ..annotations import get_options, set_options
+
+
+def loader(filename: str, config_class: Type[Annotated]) -> Annotated:
+    """Load configuration from JSON file"""
+    with open(filename, 'r', encoding='ascii') as fp:
+        conf = json.load(fp)
+
+    if not isinstance(conf, dict):
+        # TODO: add unlimited depth support
+        raise InvalidConfigFile('JSON configuration structure must be dict[str, dict[str, any]]')
+
+    config = get_options(config_class)
+
+    for module_name, options in config.items():
+        module_conf = config.get(module_name, {})
+        for option_name, (option_type, default_value) in options.items():
+            try:
+                value = option_type(module_conf[option_name])
+            except KeyError:
+                value = default_value
+            except Exception as error:
+                value = error
+
+            options[option_name] = value
+
+    config_instance = config_class()
+    set_options(config_instance, config)
+    return config_instance

aiobp-0.1.0/aiobp/logging/__init__.py

@@ -0,0 +1,4 @@
+from . import log
+from .custom import LoggingConfig, add_devel_log_level, setup_logging
+
+__all__ = ["LoggingConfig", "add_devel_log_level", "log", "setup_logging"]

aiobp-0.1.0/aiobp/logging/custom.py

@@ -0,0 +1,100 @@
+"""Customize Python logger"""
+
+import logging
+import logging.handlers
+import sys
+
+from typing import Optional
+
+
+class LoggingConfig:
+    """Loging configuration"""
+
+    level: str = 'DEBUG'
+    filename: Optional[str] = None
+
+
+class Color:
+    """Console colors"""
+
+    black = "\x1b[0;30m"
+    brown = "\x1b[0;31m"
+    dark_green = "\x1b[0;32m"
+    orange = "\x1b[0;33m"
+    dark_blue = "\x1b[0;34m"
+    purple = "\x1b[0;35m"
+    teal = "\x1b[0;36m"
+    grey = "\x1b[0;37m"
+    red = "\x1b[0;91m"
+    green = "\x1b[0;92m"
+    yellow = "\x1b[0;93m"
+    blue = "\x1b[0;94m"
+    magenta = "\x1b[0;95m"
+    cyan = "\x1b[0;96m"
+    white = "\x1b[0;97m"
+    reset = "\x1b[0m"
+
+
+class PrefixExceptionFormatter(logging.Formatter):
+    """Add date in front of each line of multiline exception/stack trace"""
+
+    def _prefix_text(self, prefix: str, stack: str, color: Color = Color.brown) -> str:
+        """Prefix lines with date so we can easily grep by date and time"""
+        return "\n".join([f"{prefix} {color}{line}{Color.reset}" for line in stack.split("\n")][1:])
+
+
+class ColorFormatter(PrefixExceptionFormatter):
+    """Color formatter for console logging"""
+
+    severity_color = {
+        logging.DEBUG: Color.grey,
+        logging.INFO: Color.white,
+        logging.WARNING: Color.orange,
+        logging.ERROR: Color.red,
+        logging.CRITICAL: Color.magenta,
+    }
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format message according to its severity level"""
+        color = ColorFormatter.severity_color.get(record.levelno, Color.blue)
+        record.message = f"{color}{record.getMessage()}{Color.reset}"
+        if self.usesTime():
+            record.asctime = self.formatTime(record, self.datefmt)
+        s = self.formatMessage(record)
+        if record.exc_info:
+            # Cache the traceback text to avoid converting it multiple times
+            # (it's constant anyway)
+            if not record.exc_text:
+                record.exc_text = self.formatException(record.exc_info)
+        if record.exc_text:
+            if s[-1:] != "\n":
+                s = s + "\n"
+            s = s + self._prefix_text(record.asctime, record.exc_text)
+        if record.stack_info:
+            if s[-1:] != "\n":
+                s = s + "\n"
+            s = s + self._prefix_text(record.asctime, self.formatStack(record.stack_info))
+        return s
+
+
+def add_devel_log_level():
+    """Register new logging level for development purposes"""
+    logging.addLevelName(1, "DEVEL")
+
+
+def setup_logging(config: Optional[LoggingConfig] = LoggingConfig()) -> None:
+    """Setup Python logger"""
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setFormatter(
+        ColorFormatter(f"%(asctime)s [{Color.green}%(filename)s:%(lineno)d{Color.reset}] %(message)s"),
+    )
+    handlers = [console_handler]
+
+    if config.filename is not None:
+        file_handler = logging.handlers.WatchedFileHandler(filename=config.filename)
+        file_handler.setFormatter(
+            PrefixExceptionFormatter("%(asctime)s %(levelname)s [%(filename)s:%(lineno)d] %(message)s"),
+        )
+        handlers.append(file_handler)
+
+    logging.basicConfig(level=config.level, handlers=handlers)

aiobp-0.1.0/aiobp/logging/log.py

@@ -0,0 +1,13 @@
+"""Add dev and trace logging shortcuts"""
+
+import functools
+import logging
+
+
+dev = functools.partial(logging.log, 1)
+debug = logging.debug
+info = logging.info
+warning = logging.warning
+error = logging.error
+critical = logging.critical
+trace = functools.partial(logging.log, logging.ERROR, exc_info=True)

aiobp-0.1.0/aiobp/runner.py

@@ -0,0 +1,228 @@
+"""Run asyncio coroutine as endless service and handle graceful shutdown"""
+
+import asyncio
+import os
+import signal
+import time
+
+from typing import Coroutine, Any, Optional, Callable, Union
+
+from .logging import log
+from .task import create_task
+
+
+__on_shutdown: list[tuple[Callable[..., Coroutine], list[Any], bool]] = []  # to gracefully close connections
+
+
+def on_shutdown(
+    # instead of ..., there should be generic TypeVar reflected to args
+    # however python type system doesn't seem to be capable of that yet
+    coroutine: Callable[..., Coroutine],
+    args: Optional[list[Any]] = None,
+    after_tasks_cancel: bool = False,
+) -> None:
+    """Register coroutine to be called on graceful shutdown
+
+    Coroutines are called in LIFO order. By default, coroutines are called
+    BEFORE all tasks are canceled and awaited for graceful completion.
+
+    If after_tasks_cancel is set to True then the coroutine is called
+    AFTER canceling all tasks and waiting for their possible timeout.
+    Useful for ClientSession.close() for example.
+    """
+    if args is None:
+        args = []
+    __on_shutdown.append((coroutine, args, after_tasks_cancel))
+    log_args = ",".join(repr(arg) for arg in args)
+    log_when = "after" if after_tasks_cancel else "before"
+    log.debug("Will call %s(%s) on shutdown %s tasks cancelation", coroutine, log_args, log_when)
+
+
+def log_awaitable(awaitable: Union[asyncio.Task, Coroutine]) -> str:
+    """Make good task description for log"""
+    coroutine = awaitable.get_coro() if isinstance(awaitable, asyncio.Task) else awaitable
+    if not asyncio.iscoroutine(coroutine):
+        return repr(coroutine)
+
+    code = coroutine.cr_code
+
+    cwd = os.getcwd()
+    filename = code.co_filename
+    if filename.startswith(cwd):
+        filename = filename[len(cwd) + 1 :]
+
+    if awaitable == coroutine:  # it was coroutine, not a task
+        return f'<{filename}:{code.co_firstlineno} method "{code.co_name}">'
+
+    return f'<{awaitable.get_name()} {filename}:{code.co_firstlineno} metod "{code.co_name}">'
+
+
+# Needed up to Python 3.10, when we upgrade to Python 3.11 we can use builtin asyncio.run()
+def runner(service: Coroutine, shutdown_timeout: float = 5.0) -> None:
+    """Run given service in asyncio.Task and handle SIGTERM/KeyboardInterrupt"""
+    loop = asyncio.get_event_loop()
+    # main does:
+    # 1. start given service coroutine as task
+    # 2. add SIGTERM and SIGINT handlers
+    # 3. waits for kill or KeyboardInterrupt
+    loop.run_until_complete(__main(service))
+    # graceful_shutdown does:
+    # 1. calls one by one all registered coroutines via on_shutdown(...) in LIFO order
+    # 2. cancel all tasks in parallel (via gather)
+    # 3. await tasks to finish in specified shutdown_timeout
+    # 4. calls all registered coroutines via on_shutdown(..., after_tasks_cancel=True) in LIFO order
+    loop.run_until_complete(__graceful_shutdown(shutdown_timeout))
+
+
+async def __main(service: Coroutine) -> None:
+    """Run main service in task and await for SIGTERM"""
+    create_task(service, "MainTask")
+
+    shutdown_event = asyncio.Event()
+    loop = asyncio.get_event_loop()
+    loop.add_signal_handler(signal.SIGTERM, shutdown_event.set)
+    loop.add_signal_handler(signal.SIGINT, shutdown_event.set)
+    # endless wait for shutdown
+    try:
+        await shutdown_event.wait()
+    except asyncio.CancelledError:
+        pass
+
+
+async def __graceful_shutdown(timeout: float = 5.0) -> None:
+    """Gracefully shutdown coroutines and tasks"""
+    log.info(f"Graceful shutdown up to {timeout:.3f} s...")
+    remains = timeout
+    remains = await __shutdown_coroutines(timeout=remains, after_tasks_cancel=False)
+    remains = await __shutdown_tasks(timeout=remains)
+    remains = await __shutdown_coroutines(timeout=remains, after_tasks_cancel=True)
+    if remains > 0:
+        log.info("Shutdown completed in %.3f s", (timeout - remains))
+    else:
+        log.warning("Shutdown not completed within timeout!")
+
+
+async def __shutdown_coroutines(timeout: float, after_tasks_cancel: bool) -> float:
+    """Await for on_shutdown callbacks finish with timeout"""
+    log.debug(f"Shutting down coroutines {'after' if after_tasks_cancel else 'before'} tasks cancel...")
+
+    for coro, args, when in __on_shutdown[::-1]:
+        if when != after_tasks_cancel:
+            continue
+
+        start = time.time()
+        log_args = ",".join(repr(arg) for arg in args)
+        try:
+            coroutine = coro(*args)
+        except Exception:
+            log.trace('Exception in %s(%s)', coro.__name__, log_args)
+            took = time.time() - start
+            timeout -= took
+            continue
+
+        if not asyncio.iscoroutine(coroutine):  # we may get just plain synchronous method
+            took = time.time() - start
+            timeout -= took
+            continue
+
+        try:
+            result = await asyncio.wait_for(coroutine, timeout=timeout)
+            log.debug("Coroutine finished: %s(%s) -> %r", log_awaitable(coro), log_args, result)
+        except asyncio.TimeoutError:
+            log.error("Coroutine did not finish in timeout: %s(%s)", log_awaitable(coro), log_args)
+        except Exception as error:  # pylint: disable=broad-exception-caught
+            log.error("Coroutine shutdown failed %s(%s): %r", log_awaitable(coro), log_args, error)
+        took = time.time() - start
+        timeout -= took
+
+    return timeout
+
+
+async def __shutdown_tasks(timeout: float) -> float:
+    """Gather tasks and await for their finish with timeout"""
+    log.debug('Shutting down tasks...')
+
+    start = time.time()
+
+    tasks = asyncio.all_tasks()
+    tasks.discard(asyncio.current_task())  # don't touch ourselves
+    for task in tasks:
+        task.cancel()
+    # We must await.sleep(0) here so task.cancel() is actually processed
+    # and await in the task's coroutine is interrupted.
+    await asyncio.sleep(0)
+
+    for task in tasks.copy():
+        if __task_failed(task, "%s await must be in try/except!") or task.done():
+            # don't wait for failed task because they never gather
+            tasks.remove(task)
+
+    if not tasks:
+        log.debug("No tasks to gracefully shutdown")
+        took = time.time() - start
+        return timeout - took
+
+    try:
+        log.debug(f"Waiting up to {timeout:.3f} s for tasks to finish...")
+        await asyncio.wait_for(asyncio.gather(*tasks, return_exceptions=True), timeout=timeout)
+        log.debug("All tasks finished within timeout")
+    except asyncio.TimeoutError:
+        log.warning('Nope, they get interrupted')
+        pass
+
+    for task in tasks:
+        if not task.done():
+            # Task didn't finish before timeout. Is it a bug in task code executed after cancel
+            # or is the timeout too short to finish all needed work by task?
+            log.error("Task did not finish gracefully: %s", log_awaitable(task))
+            continue
+
+        __task_failed(task, "%s didn't finish in shutdown timeout")
+
+    took = time.time() - start
+    return timeout - took
+
+
+def __prepare_coroutines(after_tasks_cancel: bool) -> set[asyncio.Task]:
+    """Prepare coroutines for shutdown"""
+    tasks = set()
+    for coro, args, when in __on_shutdown[::-1]:
+        if when != after_tasks_cancel:
+            continue
+
+        try:
+            coroutine = coro(*args)
+        except Exception:
+            log_args = ",".join(repr(arg) for arg in args)
+            log.trace('Exception in %s(%s)', coro.__name__, log_args)
+            continue
+
+        if not asyncio.iscoroutine(coroutine):  # we may get just plain synchronous method
+            continue
+
+        try:
+            tasks.add(create_task(coroutine, name="OnShutdown"))
+        except Exception as error:  # pylint: disable=broad-exception-caught
+            log_args = ",".join(repr(arg) for arg in args)
+            log.error("Unable to prepare for graceful shutdown %s(%s): %r", coro, log_args, error)
+
+    return tasks
+
+
+def __task_failed(task: asyncio.Task, canceled_msg: str) -> bool:
+    """Log task result/exception and return if exception happened in its coroutine"""
+    if not task.done():
+        return False
+
+    try:
+        result = task.result()
+        log.debug("Task %s finished with result: %r", log_awaitable(task), result)
+        return False
+
+    except asyncio.CancelledError:
+        log.trace(canceled_msg, log_awaitable(task))
+
+    except Exception as error:  # pylint: disable=broad-exception-caught
+        log.trace("%s in task %s: %s", error.__class__.__name__, log_awaitable(task), error)
+
+    return True

aiobp-0.1.0/aiobp/task.py

@@ -0,0 +1,20 @@
+"""Keep reference to running asyncio tasks"""
+
+import asyncio
+
+from typing import Coroutine
+
+
+__tasks: set[asyncio.Task] = set()  # to avoid garbage collection by holding reference
+
+
+def create_task(coroutine: Coroutine, name: str) -> asyncio.Task:
+    """Creates task and keeps reference until the task is done
+
+    Argument "name" is optional in asyncio.task(), however we require it
+    to make our code easier to debug.
+    """
+    task = asyncio.create_task(coroutine, name=name)
+    __tasks.add(task)
+    task.add_done_callback(__tasks.discard)
+    return task

aiobp-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[tool.poetry]
+name = "aiobp"
+version = "0.1.0"
+description = "Boilerplate for asyncio service"
+authors = ["INSOFT s.r.o."]
+readme = "README.md"
+packages = [{ include = "aiobp" }]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+
+[tool.poetry.group.dev.dependencies]
+mypy = "^1.8.0"
+pylint = "^3.0.3"
+ruff = "^0.1.13"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"