omlish 0.0.0.dev216__tar.gz → 0.0.0.dev218__tar.gz

{omlish-0.0.0.dev216/omlish.egg-info → omlish-0.0.0.dev218}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: omlish
-Version: 0.0.0.dev216
+Version: 0.0.0.dev218
 Summary: omlish
 Author: wrmsr
 License: BSD-3-Clause

{omlish-0.0.0.dev216 → omlish-0.0.0.dev218}/omlish/__about__.py

@@ -1,5 +1,5 @@
-__version__ = '0.0.0.dev216'
-__revision__ = '4805bde6bf1ddb3b6c2099d185808394e0634392'
+__version__ = '0.0.0.dev218'
+__revision__ = '0d15b9d5ec9832621506a90856baf7d140dd63ad'
 
 
 #

omlish-0.0.0.dev218/omlish/asyncs/asyncio/all.py

@@ -0,0 +1,7 @@
+# ruff: noqa: I001
+from .asyncio import (  # noqa
+    asyncio_once as once,
+    asyncio_wait_concurrent as wait_concurrent,
+    drain_asyncio_tasks as drain_tasks,
+    draining_asyncio_tasks as draining_tasks,
+)

{omlish-0.0.0.dev216 → omlish-0.0.0.dev218}/omlish/dataclasses/__init__.py

@@ -93,8 +93,6 @@ from .impl.reflect import (  # noqa
 from .utils import (  # noqa
     is_immediate_dataclass,
 
-    maybe_post_init,
-
     opt_repr,
     truthy_repr,
 
@@ -113,3 +111,9 @@ from .utils import (  # noqa
     iter_keys,
     iter_values,
 )
+
+##
+
+from ..lite.dataclasses import (  # noqa
+    dataclass_maybe_post_init as maybe_post_init,
+)

{omlish-0.0.0.dev216 → omlish-0.0.0.dev218}/omlish/dataclasses/utils.py

@@ -26,18 +26,6 @@ def is_immediate_dataclass(cls: type) -> bool:
 ##
 
 
-def maybe_post_init(sup: ta.Any) -> bool:
-    try:
-        fn = sup.__post_init__
-    except AttributeError:
-        return False
-    fn()
-    return True
-
-
-##
-
-
 def opt_repr(o: ta.Any) -> str | None:
     return repr(o) if o is not None else None
 

omlish-0.0.0.dev218/omlish/docker/oci/data.py

@@ -0,0 +1,71 @@
+# ruff: noqa: UP006 UP007
+# @omlish-lite
+import abc
+import dataclasses as dc
+import typing as ta
+
+from ...lite.marshal import OBJ_MARSHALER_FIELD_KEY
+from ...lite.marshal import OBJ_MARSHALER_OMIT_IF_NONE
+
+
+##
+
+
+@dc.dataclass(frozen=True)
+class OciDataclass(abc.ABC):  # noqa
+    pass
+
+
+##
+
+
+@dc.dataclass(frozen=True)
+class OciImageConfig(OciDataclass):
+    """https://github.com/opencontainers/image-spec/blob/92353b0bee778725c617e7d57317b568a7796bd0/config.md"""
+
+    architecture: str
+    os: str
+
+    @dc.dataclass(frozen=True)
+    class RootFs:
+        type: str
+        diff_ids: ta.Sequence[str]
+
+    rootfs: RootFs
+
+    #
+
+    created: ta.Optional[str] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})
+    author: ta.Optional[str] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})
+    os_version: ta.Optional[str] = dc.field(default=None, metadata={OBJ_MARSHALER_FIELD_KEY: 'os.version', OBJ_MARSHALER_OMIT_IF_NONE: True})  # noqa
+    os_features: ta.Optional[ta.Sequence[str]] = dc.field(default=None, metadata={OBJ_MARSHALER_FIELD_KEY: 'os.features', OBJ_MARSHALER_OMIT_IF_NONE: True})  # noqa
+    variant: ta.Optional[str] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})
+
+    """
+    config object, OPTIONAL
+        User string, OPTIONAL
+        ExposedPorts object, OPTIONAL
+        Env array of strings, OPTIONAL
+        Entrypoint array of strings, OPTIONAL
+        Cmd array of strings, OPTIONAL
+        Volumes object, OPTIONAL
+        WorkingDir string, OPTIONAL
+        Labels object, OPTIONAL
+        StopSignal string, OPTIONAL
+        ArgsEscaped boolean, OPTIONAL
+        Memory integer, OPTIONAL
+        MemorySwap integer, OPTIONAL
+        CpuShares integer, OPTIONAL
+        Healthcheck object, OPTIONAL
+    """
+    config: ta.Optional[ta.Mapping[str, ta.Any]] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})
+
+    @dc.dataclass(frozen=True)
+    class History:
+        created: ta.Optional[str] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})
+        author: ta.Optional[str] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})
+        created_by: ta.Optional[str] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})
+        comment: ta.Optional[str] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})
+        empty_layer: ta.Optional[bool] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})
+
+    history: ta.Optional[ta.Sequence[History]] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})

omlish-0.0.0.dev218/omlish/docker/oci/media.py

@@ -0,0 +1,124 @@
+# ruff: noqa: UP006 UP007
+# @omlish-lite
+import abc
+import dataclasses as dc
+import typing as ta
+
+from ...lite.check import check
+from ...lite.marshal import OBJ_MARSHALER_FIELD_KEY
+from ...lite.marshal import OBJ_MARSHALER_OMIT_IF_NONE
+from ...lite.marshal import unmarshal_obj
+from .data import OciDataclass
+from .data import OciImageConfig
+
+
+##
+
+
+@dc.dataclass(frozen=True)
+class OciMediaDataclass(OciDataclass, abc.ABC):  # noqa
+    SCHEMA_VERSION: ta.ClassVar[int]
+    MEDIA_TYPE: ta.ClassVar[str]
+
+
+_REGISTERED_OCI_MEDIA_DATACLASSES: ta.Dict[str, ta.Type[OciMediaDataclass]] = {}
+
+
+def _register_oci_media_dataclass(cls):
+    check.issubclass(cls, OciMediaDataclass)
+    check.arg(dc.is_dataclass(cls))
+    mt = check.non_empty_str(cls.__dict__['MEDIA_TYPE'])
+    check.not_in(mt, _REGISTERED_OCI_MEDIA_DATACLASSES)
+    _REGISTERED_OCI_MEDIA_DATACLASSES[mt] = cls
+    return cls
+
+
+def get_registered_oci_media_dataclass(media_type: str) -> ta.Optional[ta.Type[OciMediaDataclass]]:
+    return _REGISTERED_OCI_MEDIA_DATACLASSES.get(media_type)
+
+
+def unmarshal_oci_media_dataclass(
+        dct: ta.Mapping[str, ta.Any],
+        *,
+        media_type: ta.Optional[str] = None,
+) -> ta.Any:
+    if media_type is None:
+        media_type = check.non_empty_str(dct['mediaType'])
+    cls = _REGISTERED_OCI_MEDIA_DATACLASSES[media_type]
+    return unmarshal_obj(dct, cls)
+
+
+#
+
+
+@dc.dataclass(frozen=True)
+class OciMediaDescriptor(OciDataclass):
+    """https://github.com/opencontainers/image-spec/blob/92353b0bee778725c617e7d57317b568a7796bd0/descriptor.md#properties"""  # noqa
+
+    media_type: str = dc.field(metadata={OBJ_MARSHALER_FIELD_KEY: 'mediaType'})
+    digest: str
+    size: int
+
+    #
+
+    urls: ta.Optional[ta.Sequence[str]] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})
+    annotations: ta.Optional[ta.Mapping[str, str]] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})  # noqa
+    data: ta.Optional[str] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})
+    artifact_type: ta.Optional[str] = dc.field(default=None, metadata={OBJ_MARSHALER_FIELD_KEY: 'artifactType', OBJ_MARSHALER_OMIT_IF_NONE: True})  # noqa
+
+    #
+
+    platform: ta.Optional[ta.Mapping[str, ta.Any]] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})  # noqa
+
+
+@_register_oci_media_dataclass
+@dc.dataclass(frozen=True)
+class OciMediaImageIndex(OciMediaDataclass):
+    """https://github.com/opencontainers/image-spec/blob/92353b0bee778725c617e7d57317b568a7796bd0/image-index.md"""
+
+    manifests: ta.Sequence[OciMediaDescriptor]  # -> OciMediaImageIndex | OciMediaImageManifest
+
+    #
+
+    annotations: ta.Optional[ta.Mapping[str, str]] = dc.field(default=None, metadata={OBJ_MARSHALER_OMIT_IF_NONE: True})  # noqa
+
+    #
+
+    SCHEMA_VERSION: ta.ClassVar[int] = 2
+    schema_version: int = dc.field(default=SCHEMA_VERSION, metadata={OBJ_MARSHALER_FIELD_KEY: 'schemaVersion'})
+
+    MEDIA_TYPE: ta.ClassVar[str] = 'application/vnd.oci.image.index.v1+json'
+    media_type: str = dc.field(default=MEDIA_TYPE, metadata={OBJ_MARSHALER_FIELD_KEY: 'mediaType'})
+
+
+@_register_oci_media_dataclass
+@dc.dataclass(frozen=True)
+class OciMediaImageManifest(OciMediaDataclass):
+    """https://github.com/opencontainers/image-spec/blob/92353b0bee778725c617e7d57317b568a7796bd0/manifest.md"""
+
+    config: OciMediaDescriptor  # -> OciMediaImageConfig
+
+    # MEDIA_TYPES: ta.ClassVar[ta.Mapping[str, str]] = {
+    #     'TAR': 'application/vnd.oci.image.layer.v1.tar',
+    #     'TAR_GZIP': 'application/vnd.oci.image.layer.v1.tar+gzip',
+    #     'TAR_ZSTD': 'application/vnd.oci.image.layer.v1.tar+zstd',
+    # }
+    layers: ta.Sequence[OciMediaDescriptor]
+
+    #
+
+    SCHEMA_VERSION: ta.ClassVar[int] = 2
+    schema_version: int = dc.field(default=SCHEMA_VERSION, metadata={OBJ_MARSHALER_FIELD_KEY: 'schemaVersion'})
+
+    MEDIA_TYPE: ta.ClassVar[str] = 'application/vnd.oci.image.manifest.v1+json'
+    media_type: str = dc.field(default=MEDIA_TYPE, metadata={OBJ_MARSHALER_FIELD_KEY: 'mediaType'})
+
+
+@_register_oci_media_dataclass
+@dc.dataclass(frozen=True)
+class OciMediaImageConfig(OciImageConfig, OciMediaDataclass):
+    SCHEMA_VERSION: ta.ClassVar[int] = 2
+    schema_version: int = dc.field(default=SCHEMA_VERSION, metadata={OBJ_MARSHALER_FIELD_KEY: 'schemaVersion'})
+
+    MEDIA_TYPE: ta.ClassVar[str] = 'application/vnd.oci.image.config.v1+json'
+    media_type: str = dc.field(default=MEDIA_TYPE, metadata={OBJ_MARSHALER_FIELD_KEY: 'mediaType'})

omlish-0.0.0.dev218/omlish/docker/portrelay.py

@@ -0,0 +1,49 @@
+# ruff: noqa: UP006 UP007
+# @omlish-lite
+import dataclasses as dc
+import os
+import typing as ta
+
+
+@dc.dataclass(frozen=True)
+class DockerPortRelay:
+    docker_port: int
+    host_port: int
+
+    name: ta.Optional[str] = None
+
+    DEFAULT_HOST_NAME: ta.ClassVar[str] = 'host.docker.internal'
+    host_name: str = DEFAULT_HOST_NAME
+
+    DEFAULT_INTERMEDIATE_PORT: ta.ClassVar[int] = 5000
+    intermediate_port: int = DEFAULT_INTERMEDIATE_PORT
+
+    DEFAULT_IMAGE: ta.ClassVar[str] = 'alpine/socat'
+    image: str = DEFAULT_IMAGE
+
+    def socat_args(self) -> ta.List[str]:
+        return [
+            '-d',
+            f'TCP-LISTEN:{self.intermediate_port},fork,reuseaddr',
+            f'TCP:{self.host_name}:{self.host_port}',
+        ]
+
+    def run_args(self) -> ta.List[str]:
+        if (name := self.name) is None:
+            name = f'docker_port_relay-{os.getpid()}'
+
+        return [
+            '--name', name,
+            '--rm',
+            '-p', f'{self.docker_port}:{self.intermediate_port}',
+            self.image,
+            *self.socat_args(),
+        ]
+
+    def run_cmd(self) -> ta.List[str]:
+        return [
+            'docker',
+            'run',
+            '-i',
+            *self.run_args(),
+        ]

{omlish-0.0.0.dev216 → omlish-0.0.0.dev218}/omlish/formats/json5/Json5.g4

@@ -6,9 +6,6 @@
 // See https://json5.org/
 // Derived from ../json/JSON.g4 which original derived from http://json.org
 
-// $antlr-format alignTrailingComments true, columnLimit 150, minEmptyLines 1, maxEmptyLinesToKeep 1, reflowComments false, useTab false
-// $antlr-format allowShortRulesOnASingleLine false, allowShortBlocksOnASingleLine true, alignSemicolons hanging, alignColons hanging
-
 grammar Json5;
 
 json5

{omlish-0.0.0.dev216 → omlish-0.0.0.dev218}/omlish/http/coro/server.py

@@ -65,9 +65,12 @@ import typing as ta
 
 from ...lite.check import check
 from ...sockets.addresses import SocketAddress
-from ...sockets.handlers import SocketHandler
+from ...sockets.handlers import SocketHandler  # noqa
+from ...sockets.io import SocketIoPair
 from ..handlers import HttpHandler
 from ..handlers import HttpHandlerRequest
+from ..handlers import HttpHandlerResponseData
+from ..handlers import HttpHandlerResponseStreamedData
 from ..handlers import UnsupportedMethodHttpHandlerError
 from ..parsing import EmptyParsedHttpResult
 from ..parsing import HttpRequestParser
@@ -193,7 +196,7 @@ class CoroHttpServer:
 
         message: ta.Optional[str] = None
         headers: ta.Optional[ta.Sequence['CoroHttpServer._Header']] = None
-        data: ta.Optional[bytes] = None
+        data: ta.Optional[HttpHandlerResponseData] = None
         close_connection: ta.Optional[bool] = False
 
         def get_header(self, key: str) -> ta.Optional['CoroHttpServer._Header']:
@@ -204,7 +207,7 @@ class CoroHttpServer:
 
     #
 
-    def _build_response_bytes(self, a: _Response) -> bytes:
+    def _build_response_head_bytes(self, a: _Response) -> bytes:
         out = io.BytesIO()
 
         if a.version >= HttpProtocolVersions.HTTP_1_0:
@@ -219,11 +222,22 @@ class CoroHttpServer:
 
             out.write(b'\r\n')
 
-        if a.data is not None:
-            out.write(a.data)
-
         return out.getvalue()
 
+    def _yield_response_data(self, a: _Response) -> ta.Iterator[bytes]:
+        if a.data is None:
+            return
+
+        elif isinstance(a.data, bytes):
+            yield a.data
+            return
+
+        elif isinstance(a.data, HttpHandlerResponseStreamedData):
+            yield from a.data.iter
+
+        else:
+            raise TypeError(a.data)
+
     #
 
     DEFAULT_CONTENT_TYPE = 'text/plain'
@@ -234,8 +248,17 @@ class CoroHttpServer:
 
         if resp.get_header('Content-Type') is None:
             nh.append(self._Header('Content-Type', self._default_content_type))
+
         if resp.data is not None and resp.get_header('Content-Length') is None:
-            nh.append(self._Header('Content-Length', str(len(resp.data))))
+            cl: ta.Optional[int]
+            if isinstance(resp.data, bytes):
+                cl = len(resp.data)
+            elif isinstance(resp.data, HttpHandlerResponseStreamedData):
+                cl = resp.data.length
+            else:
+                raise TypeError(resp.data)
+            if cl is not None:
+                nh.append(self._Header('Content-Length', str(cl)))
 
         if nh:
             kw.update(headers=[*(resp.headers or []), *nh])
@@ -409,9 +432,13 @@ class CoroHttpServer:
 
                 elif isinstance(o, self._Response):
                     i = None
+
                     r = self._preprocess_response(o)
-                    b = self._build_response_bytes(r)
-                    check.none((yield self.WriteIo(b)))
+                    hb = self._build_response_head_bytes(r)
+                    check.none((yield self.WriteIo(hb)))
+
+                    for b in self._yield_response_data(r):
+                        yield self.WriteIo(b)
 
                 else:
                     raise TypeError(o)
@@ -530,27 +557,20 @@ class CoroHttpServer:
 ##
 
 
-class CoroHttpServerSocketHandler(SocketHandler):
+class CoroHttpServerSocketHandler:  # SocketHandler
     def __init__(
             self,
-            client_address: SocketAddress,
-            rfile: ta.BinaryIO,
-            wfile: ta.BinaryIO,
-            *,
             server_factory: CoroHttpServerFactory,
+            *,
             log_handler: ta.Optional[ta.Callable[[CoroHttpServer, CoroHttpServer.AnyLogIo], None]] = None,
     ) -> None:
-        super().__init__(
-            client_address,
-            rfile,
-            wfile,
-        )
+        super().__init__()
 
         self._server_factory = server_factory
         self._log_handler = log_handler
 
-    def handle(self) -> None:
-        server = self._server_factory(self._client_address)
+    def __call__(self, client_address: SocketAddress, fp: SocketIoPair) -> None:
+        server = self._server_factory(client_address)
 
         gen = server.coro_handle()
 
@@ -562,15 +582,15 @@ class CoroHttpServerSocketHandler(SocketHandler):
                     self._log_handler(server, o)
 
             elif isinstance(o, CoroHttpServer.ReadIo):
-                i = self._rfile.read(o.sz)
+                i = fp.r.read(o.sz)
 
             elif isinstance(o, CoroHttpServer.ReadLineIo):
-                i = self._rfile.readline(o.sz)
+                i = fp.r.readline(o.sz)
 
             elif isinstance(o, CoroHttpServer.WriteIo):
                 i = None
-                self._wfile.write(o.data)
-                self._wfile.flush()
+                fp.w.write(o.data)
+                fp.w.flush()
 
             else:
                 raise TypeError(o)

{omlish-0.0.0.dev216 → omlish-0.0.0.dev218}/omlish/http/handlers.py

@@ -9,6 +9,10 @@ from .parsing import HttpHeaders
 
 
 HttpHandler = ta.Callable[['HttpHandlerRequest'], 'HttpHandlerResponse']  # ta.TypeAlias
+HttpHandlerResponseData = ta.Union[bytes, 'HttpHandlerResponseStreamedData']  # ta.TypeAlias  # noqa
+
+
+##
 
 
 @dc.dataclass(frozen=True)
@@ -25,10 +29,16 @@ class HttpHandlerResponse:
     status: ta.Union[http.HTTPStatus, int]
 
     headers: ta.Optional[ta.Mapping[str, str]] = None
-    data: ta.Optional[bytes] = None
+    data: ta.Optional[HttpHandlerResponseData] = None
     close_connection: ta.Optional[bool] = None
 
 
+@dc.dataclass(frozen=True)
+class HttpHandlerResponseStreamedData:
+    iter: ta.Iterable[bytes]
+    length: ta.Optional[int] = None
+
+
 class HttpHandlerError(Exception):
     pass
 

{omlish-0.0.0.dev216 → omlish-0.0.0.dev218}/omlish/iterators/tools.py

@@ -45,6 +45,7 @@ def take(n: int, iterable: ta.Iterable[T]) -> list[T]:
 
 
 def chunk(n: int, iterable: ta.Iterable[T], strict: bool = False) -> ta.Iterator[list[T]]:
+    # TODO: remove with 3.13 - 3.12 doesn't support strict
     iterator = iter(functools.partial(take, n, iter(iterable)), [])
     if strict:
         def ret():

{omlish-0.0.0.dev216 → omlish-0.0.0.dev218}/omlish/lang/imports.py

@@ -281,6 +281,10 @@ class NamePackage(ta.NamedTuple):
 
 
 class _ProxyInit:
+    class _Import(ta.NamedTuple):
+        pkg: str
+        attr: str
+
     def __init__(
             self,
             name_package: NamePackage,
@@ -294,31 +298,35 @@ class _ProxyInit:
         self._globals = globals
         self._update_globals = update_globals
 
-        self._pkgs_by_attr: dict[str, str] = {}
+        self._imps_by_attr: dict[str, _ProxyInit._Import] = {}
         self._mods_by_pkgs: dict[str, ta.Any] = {}
 
     @property
     def name_package(self) -> NamePackage:
         return self._name_package
 
-    def add(self, package: str, attrs: ta.Iterable[str]) -> None:
+    def add(self, package: str, attrs: ta.Iterable[str | tuple[str, str]]) -> None:
         if isinstance(attrs, str):
             raise TypeError(attrs)
         for attr in attrs:
-            self._pkgs_by_attr[attr] = package
+            if isinstance(attr, tuple):
+                imp_attr, attr = attr
+            else:
+                imp_attr = attr
+            self._imps_by_attr[attr] = self._Import(package, imp_attr)
 
     def get(self, attr: str) -> ta.Any:
         try:
-            pkg = self._pkgs_by_attr[attr]
+            imp = self._imps_by_attr[attr]
         except KeyError:
             raise AttributeError(attr)  # noqa
 
         try:
-            mod = self._mods_by_pkgs[pkg]
+            mod = self._mods_by_pkgs[imp.pkg]
         except KeyError:
-            mod = importlib.import_module(pkg, package=self._name_package.package)
+            mod = importlib.import_module(imp.pkg, package=self._name_package.package)
 
-        val = getattr(mod, attr)
+        val = getattr(mod, imp.attr)
 
         if self._update_globals and self._globals is not None:
             self._globals[attr] = val
@@ -329,7 +337,7 @@ class _ProxyInit:
 def proxy_init(
         globals: ta.MutableMapping[str, ta.Any],  # noqa
         package: str,
-        attrs: ta.Iterable[str],
+        attrs: ta.Iterable[str | tuple[str, str]],
 ) -> None:
     if isinstance(attrs, str):
         raise TypeError(attrs)

{omlish-0.0.0.dev216 → omlish-0.0.0.dev218}/omlish/lite/dataclasses.py

@@ -34,8 +34,10 @@ def dataclass_cache_hash(
 
 
 def dataclass_maybe_post_init(sup: ta.Any) -> bool:
+    if not isinstance(sup, super):
+        raise TypeError(sup)
     try:
-        fn = sup.__post_init__
+        fn = sup.__post_init__  # type: ignore
     except AttributeError:
         return False
     fn()

{omlish-0.0.0.dev216 → omlish-0.0.0.dev218}/omlish/logs/all.py

@@ -1,3 +1,7 @@
+from .callers import (  # noqa
+    LoggingCaller,
+)
+
 from .color import (  # noqa
     ColorLogFormatter,
 )
@@ -18,6 +22,15 @@ from .noisy import (  # noqa
     silence_noisy_loggers,
 )
 
+from .protocol import (  # noqa
+    LogLevel,
+
+    Logging,
+    NopLogging,
+    AbstractLogging,
+    StdlibLogging,
+)
+
 from .proxy import (  # noqa
     ProxyLogFilterer,
     ProxyLogHandler,

omlish-0.0.0.dev218/omlish/logs/callers.py

@@ -0,0 +1,45 @@
+# ruff: noqa: UP006 UP007
+# @omlish-lite
+import io
+import sys
+import traceback
+import types
+import typing as ta
+
+
+class LoggingCaller(ta.NamedTuple):
+    filename: str
+    lineno: int
+    func: str
+    sinfo: ta.Optional[str]
+
+    @classmethod
+    def find_frame(cls, ofs: int = 0) -> types.FrameType:
+        f: ta.Any = sys._getframe(2 + ofs)  # noqa
+        while hasattr(f, 'f_code'):
+            if f.f_code.co_filename != __file__:
+                return f
+            f = f.f_back
+        raise RuntimeError
+
+    @classmethod
+    def find(cls, stack_info: bool = False) -> 'LoggingCaller':
+        f = cls.find_frame(1)
+        # TODO: ('(unknown file)', 0, '(unknown function)', None) ?
+
+        sinfo = None
+        if stack_info:
+            sio = io.StringIO()
+            sio.write('Stack (most recent call last):\n')
+            traceback.print_stack(f, file=sio)
+            sinfo = sio.getvalue()
+            sio.close()
+            if sinfo[-1] == '\n':
+                sinfo = sinfo[:-1]
+
+        return cls(
+            f.f_code.co_filename,
+            f.f_lineno,
+            f.f_code.co_name,
+            sinfo,
+        )