tarka 0.19.1__py3-none-any.whl

tarka/__init__.py

@@ -0,0 +1,10 @@
+"""
+Tarka
+
+:copyright: 2022-2025 Nándor Mátravölgyi
+:license: Apache2, see LICENSE for more details.
+"""
+
+__copyright__ = "Copyright 2022-2025 Nándor Mátravölgyi"
+__credits__ = ["Nándor Mátravölgyi"]
+__version__ = "0.19.1"

tarka/asqla/__init__.py

@@ -0,0 +1,3 @@
+"""
+This implements a slightly opinionated reusable async Alembic+SQLAlchemy setup, for well managed database persistence.
+"""

tarka/asqla/alembic.py

@@ -0,0 +1,47 @@
+import os
+from io import StringIO
+
+from alembic import command
+from alembic.config import Config
+from alembic.script import ScriptDirectory
+from sqlalchemy import Connection
+
+
+def get_alembic_config(alembic_dir: str, sqlalchemy_url: str = None) -> Config:
+    alembic_cfg = Config(os.path.join(alembic_dir, "alembic.ini"))
+    alembic_cfg.set_main_option("script_location", alembic_dir.replace("%", "%%"))
+    if sqlalchemy_url:
+        alembic_cfg.set_main_option("sqlalchemy.url", str(sqlalchemy_url).replace("%", "%%"))
+    alembic_cfg.attributes["skip-logging-setup"] = True  # do not mess up the server logging
+    return alembic_cfg
+
+
+class NoHeadRevision(Exception):
+    pass
+
+
+class AlembicHelper:
+    def __init__(self, config: Config):
+        self.config = config
+
+    def run(self, conn: Connection, alembic_command: str, *args: str) -> str:
+        """
+        Call the alembic CLI.
+        """
+        self.config.attributes["connection"] = conn
+        self.config.stdout = StringIO()
+        getattr(command, alembic_command)(self.config, *args)
+        return self.config.stdout.getvalue()
+
+    def run_strip_output(self, conn: Connection, alembic_command: str, *args: str) -> str:
+        return self.run(conn, alembic_command, *args).strip()
+
+    def get_head_revision(self) -> str:
+        """
+        Get current single head revision.
+        """
+        script = ScriptDirectory.from_config(self.config)
+        revs = list(script.get_revisions("head"))
+        if len(revs) != 1:
+            raise NoHeadRevision()
+        return revs[0].revision

tarka/asqla/database.py

@@ -0,0 +1,161 @@
+import asyncio
+from contextlib import asynccontextmanager
+from typing import Type, Dict, Any, Optional
+
+from alembic.config import Config
+from sqlalchemy import event
+from sqlalchemy.exc import DatabaseError
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncConnection, AsyncSession, AsyncEngine
+from sqlalchemy.orm import sessionmaker
+
+from tarka.asqla.alembic import get_alembic_config, AlembicHelper
+from tarka.asqla.tx import (
+    TransactionExecutor,
+    RetryableTransactionFactory,
+    SessionTransactionExecutor,
+    RetryableSessionTransactionFactory,
+)
+
+
+class Database(object):
+    engine: AsyncEngine = None
+    serializable_engine: AsyncEngine = None
+    session_maker: Type[AsyncSession] = None
+
+    def __init__(
+        self,
+        alembic_dir: str,
+        connect_url: str,
+        engine_kwargs: Dict[str, Any] = None,  # like echo, connect_args, etc.
+        session_maker_kwargs: Dict[str, Any] = None,  # like expire_on_commit, autoflush, etc.
+        aiosqlite_serializable_begin: str = "BEGIN",  # serializable tx support workaround for aiosqlite
+        tx_retry_delay: Optional[float] = None,  # tx retry delay helps to relieve db pressure at conflicts
+    ):
+        """
+        If aiosqlite is used aiosqlite_serializable_begin="BEGIN IMMEDIATE" could be better, because then no
+        conflicts can happen, each tx caller will wait in line to acquire the lock and no resources will be
+        wasted retrying. However, this does not work well with session-tx, see TODO: tx.py:105.
+        """
+        self.alembic_dir = alembic_dir
+        self._connect_url = connect_url
+        self._engine_kwargs = engine_kwargs
+        self._session_maker_kwargs = session_maker_kwargs
+        self._aiosqlite_serializable_begin = aiosqlite_serializable_begin
+        self._tx_retry_delay = tx_retry_delay
+        self.alembic_head_at_startup = ""
+
+    def get_alembic_config(self) -> Config:
+        return get_alembic_config(self.alembic_dir, str(self.engine.sync_engine.url))
+
+    async def _init_engine(self):
+        """
+        If further customization is necessary for the engines, this shall be overridden.
+        To switch SQLite to WAL mode for example:
+
+            if self.engine.dialect.name == "sqlite":
+                @event.listens_for(self.engine.sync_engine, "connect")
+                def _setup_sqlite_connection(dbapi_con, con_record):
+                    dbapi_con.execute("PRAGMA journal_mode = WAL;")
+                    dbapi_con.execute("PRAGMA synchronous = NORMAL;")
+        """
+        self.engine = create_async_engine(self._connect_url, **(self._engine_kwargs or {}))
+        self.serializable_engine = self.engine.execution_options(isolation_level="SERIALIZABLE")
+        if self.engine.driver == "aiosqlite" and self._aiosqlite_serializable_begin:
+            # aiosqlite (<=0.20) does not honor the isolation_level with appropriate BEGIN commands, in fact it
+            # never issues begin commands, transactions always start implicitly for reads.
+            # SQLite itself does not support concurrent mutating transactions in any mode. In WAL journal_mode, there
+            # can be parallel and concurrent readers, but writing is always with an exclusive lock. In this sense "any"
+            # transaction will actually be serializable provided that an explicit BEGIN is emitted. The actual
+            # difference is the point and time that parallel connections encounter locking errors.
+            # The workaround (if not disabled) is to explicitly execute a BEGIN command at transaction start.
+            # The command can be set for the database (DEFERRED, IMMEDIATE or EXCLUSIVE) when relevant.
+            @event.listens_for(self.serializable_engine.sync_engine, "begin")
+            def do_begin(conn):
+                conn.exec_driver_sql(self._aiosqlite_serializable_begin)
+
+        self.session_maker = sessionmaker(self.engine, class_=AsyncSession, **(self._session_maker_kwargs or {}))
+
+    async def startup(self):
+        """
+        Initialize engine first, then bootstrap or migrate schema of the database to be up-to-date.
+        """
+        await self._init_engine()
+        alembic_helper = AlembicHelper(self.get_alembic_config())
+        retry = 0
+        while True:  # handle conflicting migration attempt by parallel workers
+            try:
+                async with self.engine.begin() as connection:
+                    connection: AsyncConnection
+                    self.alembic_head_at_startup = await connection.run_sync(alembic_helper.run_strip_output, "current")
+
+                    await self._upgrade(alembic_helper, connection)
+                    await self._start_hook(connection)
+            except DatabaseError:
+                if retry >= 5:
+                    raise
+                retry += 1
+                await asyncio.sleep(0.25)
+            else:
+                break
+
+    async def _upgrade(self, alembic_helper: AlembicHelper, connection: AsyncConnection):
+        if not self.alembic_head_at_startup.endswith(" (head)"):
+            await self._pre_upgrade_hook(connection)
+            await connection.run_sync(alembic_helper.run, "upgrade", "head")
+            await self._post_upgrade_hook(connection)
+
+    async def _pre_upgrade_hook(self, connection: AsyncConnection):
+        """
+        Place to put custom DDL commands before alembic upgrade.
+        Keep in mind that it is usually better to implement all changes as alembic revisions.
+        NOTE: This is called before bootstrap (first upgrade) as well.
+        """
+
+    async def _post_upgrade_hook(self, connection: AsyncConnection):
+        """
+        Place to put custom DDL commands after alembic upgrade.
+        Keep in mind that it is usually better to implement all changes as alembic revisions.
+        """
+
+    async def _start_hook(self, connection: AsyncConnection):
+        """
+        Place to put custom DDL commands that are executed each time a server starts.
+        The connection is currently at the HEAD alembic revision, in the upgrade transaction.
+        """
+
+    async def shutdown(self):
+        await self.engine.dispose()
+
+    @asynccontextmanager
+    async def run(self):
+        """
+        Convenience wrapper for startup & shutdown.
+        """
+        await self.startup()
+        try:
+            yield self
+        finally:
+            await self.shutdown()
+
+    def serializable_tx(
+        self, tx_factory: RetryableTransactionFactory, retry_delay: Optional[float] = None
+    ) -> TransactionExecutor:
+        """
+        Get a transaction executor with SERIALIZABLE isolation_level and automatic retry.
+        """
+        return TransactionExecutor(
+            self.serializable_engine, tx_factory, retry_delay=retry_delay or self._tx_retry_delay
+        )
+
+    def session_serializable_tx(
+        self, tx_factory: RetryableSessionTransactionFactory, retry_delay: Optional[float] = None
+    ) -> SessionTransactionExecutor:
+        """
+        Get an ORM transaction executor with SERIALIZABLE isolation_level and automatic retry.
+        """
+        return SessionTransactionExecutor(
+            self.session_maker,
+            tx_factory,
+            engine=self.serializable_engine,
+            retry_delay=retry_delay or self._tx_retry_delay,
+        )

tarka/asqla/postgres.py

@@ -0,0 +1,46 @@
+import warnings
+from contextlib import asynccontextmanager
+from typing import AsyncContextManager, Union
+
+from sqlalchemy import select, func
+from sqlalchemy.ext.asyncio import AsyncSession, AsyncConnection
+
+
+async def _pg_advisory_unlock(cos: Union[AsyncConnection, AsyncSession], *keys: int):
+    unlocked = (await cos.execute(select(func.pg_advisory_unlock(*keys)))).scalar_one()
+    if not unlocked:
+        warnings.warn(
+            "An inner scope has released the pg_try_advisory_lock() before the lock manager context did so explicitly. "
+            "If such is expected, then call the lock manager with 'unlock=False' or restructure the transaction and"
+            "locking to be strictly nested."
+        )
+
+
+@asynccontextmanager
+async def pg_try_advisory_lock(
+    cos: Union[AsyncConnection, AsyncSession], *keys: int, unlock: bool = True
+) -> AsyncContextManager[bool]:
+    """
+    Acquire advisory session lock, yields False if the lock was not acquired.
+    """
+    locked = (await cos.execute(select(func.pg_try_advisory_lock(*keys)))).scalar_one()
+    try:
+        yield locked
+    finally:
+        if locked and unlock:
+            await _pg_advisory_unlock(cos, *keys)
+
+
+@asynccontextmanager
+async def pg_advisory_lock(
+    cos: Union[AsyncConnection, AsyncSession], *keys: int, unlock: bool = True
+) -> AsyncContextManager:
+    """
+    Acquire advisory session lock, block until acquired.
+    """
+    (await cos.execute(select(func.pg_advisory_lock(*keys)))).scalar_one()
+    try:
+        yield
+    finally:
+        if unlock:
+            await _pg_advisory_unlock(cos, *keys)

tarka/asqla/tx.py

@@ -0,0 +1,106 @@
+import asyncio
+import inspect
+import random
+import sqlite3
+from typing import Any, Callable, Awaitable, Union, Type, Optional
+
+from sqlalchemy.exc import DBAPIError, OperationalError
+from sqlalchemy.ext.asyncio import AsyncSession, AsyncEngine, AsyncConnection
+
+
+class AbstractRetryableTransaction:
+    async def run(self) -> Any:
+        raise NotImplementedError()
+
+
+_MaybeRetryableTransaction = Union[AbstractRetryableTransaction, Awaitable[AbstractRetryableTransaction]]
+
+
+class AbstractTransactionExecutor:
+    def __init__(self, retry_delay: Optional[float] = None):
+        self.retry_delay = retry_delay if retry_delay and retry_delay > 0 else 0
+
+    async def run(self) -> Any:
+        while True:
+            try:
+                return await self._run_tx()
+            except OperationalError as e:
+                # SQLite: This catches locking errors in both the rollback and WAL modes.
+                if (
+                    isinstance(e.orig, sqlite3.OperationalError)
+                    and isinstance(e.orig.args, tuple)
+                    and len(e.orig.args) == 1
+                    and e.orig.args[0]
+                    in (
+                        "database is locked",  # normal transaction is in progress
+                        # Rarely happens when transactions are competing with "BEGIN (DEFERRED)" transactions.
+                        # Read https://sqlite.org/forum/forumpost/2507664507 for example and more info.
+                        "cannot start a transaction within a transaction",
+                    )
+                ):
+                    pass
+                else:
+                    raise e
+            except DBAPIError as e:
+                # Postgresql: https://www.postgresql.org/docs/current/mvcc-serialization-failure-handling.html
+                if e.orig and hasattr(e.orig, "sqlstate") and e.orig.sqlstate == "40001":
+                    pass
+                else:
+                    raise e
+            # TODO: implement more backend specific error handling (MariaDB, etc.)
+            if self.retry_delay > 0:
+                await asyncio.sleep(self.retry_delay * random.random())
+
+    async def _run_tx(self) -> Any:
+        raise NotImplementedError()
+
+    async def _check_run_tx(self, tmp: _MaybeRetryableTransaction) -> Any:
+        if inspect.isawaitable(tmp):
+            tmp = await tmp
+        if not isinstance(tmp, AbstractRetryableTransaction):
+            raise Exception(f"not AbstractRetryableTransaction: {tmp}")
+        return await tmp.run()
+
+
+RetryableTransactionFactory = Callable[[AsyncConnection], _MaybeRetryableTransaction]
+
+
+class TransactionExecutor(AbstractTransactionExecutor):
+
+    def __init__(
+        self, engine: AsyncEngine, tx_factory: RetryableTransactionFactory, retry_delay: Optional[float] = None
+    ):
+        AbstractTransactionExecutor.__init__(self, retry_delay)
+        self.engine = engine
+        self.tx_factory = tx_factory
+
+    async def _run_tx(self) -> Any:
+        async with self.engine.connect() as conn:
+            async with conn.begin():
+                return await self._check_run_tx(self.tx_factory(conn))
+
+
+RetryableSessionTransactionFactory = Callable[[AsyncSession], _MaybeRetryableTransaction]
+
+
+class SessionTransactionExecutor(AbstractTransactionExecutor):
+    def __init__(
+        self,
+        session_maker: Type[AsyncSession],
+        tx_factory: RetryableSessionTransactionFactory,
+        engine: Optional[AsyncEngine] = None,
+        retry_delay: Optional[float] = None,
+    ):
+        AbstractTransactionExecutor.__init__(self, retry_delay)
+        self.session_maker = session_maker
+        self.tx_factory = tx_factory
+        self._session_maker_kwargs = {}
+        if engine:
+            self._session_maker_kwargs["bind"] = engine
+
+    async def _run_tx(self) -> Any:
+        async with self.session_maker(**self._session_maker_kwargs) as session:
+            async with session.begin():
+                # TODO: The @event.listens_for(self.serializable_engine.sync_engine, "begin") hook for aiosqlite is
+                #       not called here immediately, so the "BEGIN IMMEDIATE" tx mode does not work well.
+                return await self._check_run_tx(self.tx_factory(session))

tarka/asqla/types.py

@@ -0,0 +1,20 @@
+import datetime
+
+from sqlalchemy import TypeDecorator, DateTime
+
+
+class UTCDateTime(TypeDecorator):
+    impl = DateTime
+    cache_ok = True
+
+    def process_bind_param(self, value, dialect):
+        if value is not None:
+            if not value.tzinfo:
+                raise TypeError("tzinfo is required")
+            value = value.astimezone(datetime.timezone.utc).replace(tzinfo=None)
+        return value
+
+    def process_result_value(self, value, dialect):
+        if value is not None:
+            value = value.replace(tzinfo=datetime.timezone.utc)
+        return value

tarka/logging/bootstrap.py

@@ -0,0 +1,54 @@
+import logging
+from typing import Dict
+
+from tarka.logging.handler import NamedHandlersAndHandlerConfigs, StreamHandlerConfig
+from tarka.logging.hook import setup_logging_exception_hooks
+from tarka.logging.level import LoggingLevelOrNamedLoggingLevelConfig, NamedLoggingLevelConfig
+from tarka.logging.manager import LoggerHandlerManager
+from tarka.logging.patch import TarkaLoggingPatcher
+
+
+def init_tarka_logging() -> None:
+    """
+    Use this in a top level __init__ module, to ensure the Logger.trace is patched early for use.
+    """
+    TarkaLoggingPatcher.patch_custom_level(5, "TRACE")
+
+
+def setup_basic_logging(
+    root_handlers: NamedHandlersAndHandlerConfigs = None,
+    logger_levels: Dict[str, LoggingLevelOrNamedLoggingLevelConfig] = None,
+    setup_exc_hooks: bool = True,
+    root_logger_level: LoggingLevelOrNamedLoggingLevelConfig = logging.WARNING,
+) -> None:
+    """
+    Convenience function to setup loggers and handlers easily.
+        - Setup handlers for the root logger. (because error logging shall be setup globally)
+        - Setup levels for the specified loggers.
+
+    A typical usage example:
+        parser = argparse.ArgumentParser()
+        parser.add_argument("--verbose", "-v", action="count", default=0)
+        parser.add_argument("--silent", "-s", action="count", default=0)
+        parser.add_argument("--log_file", help="path to write log to")
+        parser.add_argument("--log_backups", type=int, default=16, help="how many log files to keep when rotating")
+        args = parser.parse_args()
+        setup_basic_logging(
+            root_handlers=[RotatingFileHandlerConfig(args.log_file, backup_count=args.log_backups)],
+            logger_levels={__name__: NamedLoggingLevelConfig(args.verbose, args.silent, default=logging.INFO)},
+        )
+
+    This should be used as early as possible in the application's lifespan.
+    """
+    if not root_handlers:  # Just select stderr for default.
+        root_handlers = [StreamHandlerConfig()]
+
+    root_lhm = LoggerHandlerManager.instance()
+    root_lhm.setup_handlers(root_handlers)
+    NamedLoggingLevelConfig.apply(root_lhm.logger, root_logger_level)
+
+    for logger_name, level in (logger_levels or {}).items():
+        NamedLoggingLevelConfig.apply(logging.getLogger(logger_name), level)
+
+    if setup_exc_hooks:
+        setup_logging_exception_hooks()

tarka/logging/formatter.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import logging
+import logging.handlers
+from datetime import datetime
+from typing import Union
+
+LOGGER_FORMAT_VERBOSE = "%(asctime)s|%(levelname).1s|%(name)s:%(funcName)s:%(lineno)d| %(message)s"
+LOGGER_FORMAT_VERBOSE_THREAD = "%(asctime)s|%(thread)d|%(levelname).1s|%(name)s:%(funcName)s:%(lineno)d| %(message)s"
+LOGGER_FORMAT_TIME_CONCISE = "%y%m%d %H%M%S"
+LOGGER_FORMAT_MSEC_WITH_DOT = "%s.%03d"  # use decimal dot
+
+
+def create_logging_formatter(
+    fmt: str = None,
+    time_format: str = None,
+    msec_format: str = None,
+    concise_asctime: bool = False,
+    include_thread: bool = False,
+) -> logging.Formatter:
+    """
+    Better default formats and support for overriding the formatting of asctime, which has no API. (datefmt lacks msec)
+    """
+    if fmt:
+        pass
+    elif include_thread:
+        fmt = LOGGER_FORMAT_VERBOSE_THREAD
+    else:
+        fmt = LOGGER_FORMAT_VERBOSE
+    formatter = logging.Formatter(fmt)
+    if formatter.usesTime():  # noqa: this is not publicly documented... should be avaialable since Python 3.2
+        if time_format:
+            pass
+        elif concise_asctime:
+            time_format = LOGGER_FORMAT_TIME_CONCISE
+        else:
+            time_format = logging.Formatter.default_time_format
+        if msec_format:
+            pass
+        else:
+            msec_format = LOGGER_FORMAT_MSEC_WITH_DOT
+        msec_format % (datetime.now().strftime(time_format), 123456)  # validate
+        formatter.default_time_format = time_format
+        formatter.default_msec_format = msec_format
+    return formatter
+
+
+class HandlerFormatterConfig:
+    def __init__(
+        self,
+        fmt: str = None,
+        time_format: str = None,
+        msec_format: str = None,
+        concise_asctime: bool = False,
+        include_thread: bool = False,
+    ):
+        self.fmt = fmt
+        self.time_format = time_format
+        self.msec_format = msec_format
+        self.concise_asctime = concise_asctime
+        self.include_thread = include_thread
+
+    @property
+    def formatter(self) -> logging.Formatter:
+        return create_logging_formatter(
+            self.fmt, self.time_format, self.msec_format, self.concise_asctime, self.include_thread
+        )
+
+    @classmethod
+    def apply(cls, handler: logging.Handler, formatter: HandlerFormatterOrHandlerFormatterConfig) -> None:
+        if isinstance(formatter, HandlerFormatterConfig):
+            formatter = formatter.formatter
+        handler.setFormatter(formatter)
+
+
+HandlerFormatterOrHandlerFormatterConfig = Union[logging.Formatter, HandlerFormatterConfig]

tarka/logging/handler.py

@@ -0,0 +1,114 @@
+import logging
+import logging.handlers
+import sys
+from io import TextIOWrapper
+from pathlib import Path
+from typing import Union, Sequence, Tuple, TypeVar, Generic, Optional
+
+from tarka.logging.formatter import HandlerFormatterOrHandlerFormatterConfig, HandlerFormatterConfig
+
+_HandlerT = TypeVar("_HandlerT", bound=logging.Handler)
+
+
+class AbstractHandlerConfig(Generic[_HandlerT]):
+    name: str
+
+    def __init__(self, formatter: Optional[HandlerFormatterOrHandlerFormatterConfig]):
+        self.formatter = formatter or HandlerFormatterConfig()
+
+    def create(self) -> _HandlerT:
+        handler = self._create()
+        if self.formatter:
+            HandlerFormatterConfig.apply(handler, self.formatter)
+        return handler
+
+    def _create(self) -> _HandlerT:
+        raise NotImplementedError()
+
+
+class RotatingFileHandlerConfig(AbstractHandlerConfig[logging.handlers.RotatingFileHandler]):
+    DEFAULT_NAME = "ROTFILE"
+
+    def __init__(
+        self,
+        log_path: Union[str, Path],
+        log_file_name: str = None,
+        max_bytes: int = 4096000,
+        backup_count: int = 8,
+        ensure_directory: bool = True,
+        formatter: Optional[HandlerFormatterOrHandlerFormatterConfig] = None,
+        name: str = DEFAULT_NAME,
+    ):
+        AbstractHandlerConfig.__init__(self, formatter)
+        self.name = name
+        log_path = Path(log_path)
+        if log_file_name is None:
+            self.log_directory = log_path.parent
+            self.log_file_name = log_path.name
+        else:
+            self.log_directory = log_path
+            self.log_file_name = log_file_name
+        self.max_bytes = max_bytes
+        self.backup_count = backup_count
+        self.ensure_directory = ensure_directory
+
+    def _create(self) -> logging.handlers.RotatingFileHandler:
+        if self.ensure_directory:
+            self.log_directory.mkdir(parents=True, exist_ok=True)
+        return logging.handlers.RotatingFileHandler(
+            str(self.log_directory / self.log_file_name),
+            maxBytes=self.max_bytes,
+            backupCount=self.backup_count,
+        )
+
+
+class FileHandlerConfig(AbstractHandlerConfig[logging.FileHandler]):
+    DEFAULT_NAME = "ONEFILE"
+
+    def __init__(
+        self,
+        log_path: Union[str, Path],
+        log_file_name: str = None,
+        ensure_directory: bool = True,
+        formatter: Optional[HandlerFormatterOrHandlerFormatterConfig] = None,
+        name: str = DEFAULT_NAME,
+    ):
+        AbstractHandlerConfig.__init__(self, formatter)
+        self.name = name
+        log_path = Path(log_path)
+        if log_file_name is None:
+            self.log_directory = log_path.parent
+            self.log_file_name = log_path.name
+        else:
+            self.log_directory = log_path
+            self.log_file_name = log_file_name
+        self.ensure_directory = ensure_directory
+
+    def _create(self) -> logging.FileHandler:
+        if self.ensure_directory:
+            self.log_directory.mkdir(parents=True, exist_ok=True)
+        return logging.FileHandler(str(self.log_directory / self.log_file_name))
+
+
+class StreamHandlerConfig(AbstractHandlerConfig[logging.StreamHandler]):
+    DEFAULT_NAME = "STDERR"
+
+    def __init__(
+        self,
+        stream: TextIOWrapper = None,
+        formatter: Optional[HandlerFormatterOrHandlerFormatterConfig] = None,
+        name: str = DEFAULT_NAME,
+    ):
+        AbstractHandlerConfig.__init__(self, formatter)
+        self.name = name
+        # NOTE: We acquire the reference to the stderr stream in the method body, so we'll see the current stream
+        # if any post-import monkey-patching is being used.
+        if stream is None:
+            stream = sys.stderr
+        self.stream = stream
+
+    def _create(self) -> logging.StreamHandler:
+        return logging.StreamHandler(self.stream)
+
+
+NamedHandlersAndHandlerConfigs = Sequence[Union[Tuple[str, logging.Handler], AbstractHandlerConfig]]

tarka/logging/hook.py

@@ -0,0 +1,37 @@
+import logging
+import sys
+import threading
+
+
+def logging_excepthook(type_, value, traceback):
+    logging.getLogger().critical("Unhandled exception", exc_info=(type_, value, traceback))
+
+
+def logging_unraisablehook(unraisable):
+    logging.getLogger().critical(
+        "%s: %r",
+        "Exception ignored in" if unraisable.err_msg is None else unraisable.err_msg,
+        unraisable.object,
+        exc_info=(unraisable.exc_type, unraisable.exc_value, unraisable.exc_traceback),
+    )
+
+
+def logging_threading_excepthook(args):
+    if args.exc_type is not SystemExit:
+        logging.getLogger().critical(
+            "Unhandled exception in %r", args.thread, exc_info=(args.exc_type, args.exc_value, args.exc_traceback)
+        )
+
+
+def setup_logging_exception_hooks(
+    excepthook: bool = True, unraisablehook: bool = True, threading_excepthook: bool = True
+) -> None:
+    if excepthook and not hasattr(sys, "original_excepthook"):
+        sys.original_excepthook = sys.excepthook
+        sys.excepthook = logging_excepthook
+    if unraisablehook and not hasattr(sys, "original_unraisablehook"):
+        sys.original_unraisablehook = sys.unraisablehook
+        sys.unraisablehook = logging_unraisablehook
+    if threading_excepthook and not hasattr(threading, "original_excepthook"):
+        threading.original_excepthook = threading.excepthook
+        threading.excepthook = logging_threading_excepthook