thds.core 0.0.1__py3-none-any.whl → 1.31.20250123022540__py3-none-any.whl

thds/core/files.py

@@ -0,0 +1,125 @@
+"""Various assorted file-related utilities."""
+
+import hashlib
+import os
+import resource
+import shutil
+import stat
+import typing as ty
+from contextlib import contextmanager
+from io import BufferedWriter, TextIOWrapper
+from pathlib import Path
+
+from . import config, hashing
+from .log import getLogger
+from .tmp import temppath_same_fs
+from .types import StrOrPath
+
+FILE_SCHEME = "file://"
+logger = getLogger(__name__)
+
+
+def set_read_only(fpath: StrOrPath):
+    # thank you https://stackoverflow.com/a/51262451
+    logger.debug("Setting '%s' to read-only", fpath)
+    perms = stat.S_IMODE(os.lstat(fpath).st_mode)
+    ro_mask = 0o777 ^ (stat.S_IWRITE | stat.S_IWGRP | stat.S_IWOTH)
+    os.chmod(fpath, perms & ro_mask)
+
+
+def remove_file_scheme(uri: str) -> str:
+    """Does not require the file scheme to exist, but removes it if it's there."""
+    return uri[len(FILE_SCHEME) :] if uri.startswith(FILE_SCHEME) else uri
+
+
+def path_from_uri(uri: str) -> Path:
+    str_path = remove_file_scheme(uri)
+    if not str_path:
+        raise ValueError('Cannot convert an empty string to a Path. Did you mean to use "."?')
+    return Path(str_path)
+
+
+def to_uri(path: Path) -> str:
+    return FILE_SCHEME + os.fspath(path.resolve())
+
+
+def is_file_uri(uri: str) -> bool:
+    return uri.startswith(FILE_SCHEME)
+
+
+@contextmanager
+def atomic_write_path(destination: StrOrPath) -> ty.Iterator[Path]:
+    """Shorthand context manager for doing an atomic write (i.e., write to a temporary file,
+    then atomically move that temporary file to your final destination.
+
+    You must open and then close the file within the provided context. Unclosed files
+    will likely result in data loss or other bugs.
+    """
+    destpath = path_from_uri(destination) if isinstance(destination, str) else Path(destination)
+    with temppath_same_fs(destpath) as temp_writable_path:
+        yield temp_writable_path
+        destpath.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(temp_writable_path), destpath)
+
+
+@contextmanager
+def atomic_binary_writer(destination: StrOrPath) -> ty.Iterator[BufferedWriter]:
+    """Even shorter shorthand for writing binary data to a file, atomically."""
+    with atomic_write_path(destination) as temp_writable_path:
+        with open(temp_writable_path, "wb") as f:
+            yield f
+
+
+@contextmanager
+def atomic_text_writer(destination: StrOrPath) -> ty.Iterator[TextIOWrapper]:
+    """Even shorter shorthand for writing text data to a file, atomically."""
+    with atomic_write_path(destination) as temp_writable_path:
+        with open(temp_writable_path, "w") as f:
+            yield f
+
+
+OPEN_FILES_LIMIT = config.item("limit_open", 10000)
+
+
+def set_file_limit(n: int):
+    """Works like calling `ulimit -Sn <N>` on a Mac."""
+    resource.setrlimit(resource.RLIMIT_NOFILE, (n, n))
+    assert resource.getrlimit(resource.RLIMIT_NOFILE) == (n, n)
+
+
+def bump_limits():
+    """It was common to have to do this manually on our macs. Now that is no longer required."""
+    set_file_limit(OPEN_FILES_LIMIT())
+
+
+def shorten_filename(maybe_too_long_name: StrOrPath, max_len: int = 255, retain_last: int = 30) -> str:
+    """Shortens a filename, using a deterministic and probabilistically-unique (hash-based) algorithm.
+
+    The filename is only changed if it exceeds the provided max_len limit.
+
+    The limit defaults to 255 _bytes_ since that is what many filesystems have
+    generally supported.  https://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits
+
+    We intentionally take our 'bite' out of the middle of the filename, so that the file extension is preserved
+    and so that the first part of the path also remains human-readable.
+    """
+    # p for Path, s for str, b for bytes - too many things flying around to keep track of without this.
+    s_maybe_too_long_name = Path(maybe_too_long_name).name
+    b_filename = s_maybe_too_long_name.encode()
+
+    if len(b_filename) <= max_len:
+        # no need to mess with anything - it will 'fit' inside the root path already.
+        return s_maybe_too_long_name
+
+    b_md5_of_filename = (
+        b"-md5-" + hashing.hash_using(b_filename, hashlib.md5()).hexdigest().encode() + b"-"
+    )
+    b_last_n = b_filename[-retain_last:]
+    b_first_n = b_filename[: max_len - len(b_md5_of_filename) - len(b_last_n)]
+    b_modified_filename = b_first_n + b_md5_of_filename + b_last_n
+    assert len(b_modified_filename) <= max_len, (
+        b_modified_filename,
+        len(b_modified_filename),
+        max_len,
+    )
+    return b_modified_filename.decode()

thds/core/fretry.py

@@ -0,0 +1,115 @@
+"""A more composable retry decorator."""
+
+import random
+import time
+import typing as ty
+from functools import wraps
+from logging import getLogger
+from timeit import default_timer
+
+F = ty.TypeVar("F", bound=ty.Callable)
+
+
+IsRetryable = ty.Callable[[Exception], bool]
+RetryStrategy = ty.Iterable[IsRetryable]
+RetryStrategyFactory = ty.Callable[[], RetryStrategy]
+
+
+def expo(
+    *, retries: int, delay: float = 1.0, backoff: int = 2, jitter: bool = True
+) -> ty.Callable[[], ty.Iterator[float]]:
+    """End iteration after yielding 'retries' times.
+
+    The first retry is immediate (i.e. 0). Subsequent retries will follow the schedule
+    established by the exponential backoff algorithm. The default algorithm is 1, 3, 7,
+    15, etc., but also adds jitter.
+
+    If you want infinite exponential values, pass a negative number for 'retries'.
+    """
+
+    def expo_() -> ty.Iterator[float]:
+        count = 0
+        accum_jitter = 0.0
+        while retries < 0 or count < retries:
+            expo_delay = (backoff**count * delay) - delay  # first retry is immediate
+            if jitter:
+                jitter_delay = random.uniform(0.5, 1.5) * expo_delay
+                yield jitter_delay + accum_jitter
+                accum_jitter = expo_delay - jitter_delay
+            else:
+                yield expo_delay
+            count += 1
+
+    return expo_
+
+
+def sleep(
+    mk_seconds_iter: ty.Callable[[], ty.Iterable[float]],
+    sleeper: ty.Callable[[float], ty.Any] = time.sleep,
+) -> ty.Callable[[], ty.Iterator[str]]:
+    """A common base strategy for separating retries by sleeps.
+
+    Yield once prior to the first sleep, and once before each sleep.
+    In other words, the total number of yields is the length of the input iterable (if it is finite).
+    """
+
+    def sleep_() -> ty.Iterator[str]:
+        start = default_timer()
+
+        so_far = 0.0
+        for i, secs in enumerate(mk_seconds_iter(), start=1):
+            yield f"attempt {i} after {so_far:.2f}s"
+            so_far = default_timer() - start
+            sleeper(secs)
+
+    return sleep_
+
+
+def retry(retry_strategy_factory: RetryStrategyFactory) -> ty.Callable[[F], F]:
+    """Uses your retry strategy every time an exception is raised.
+    Your iterable can therefore provide different handling for each
+    incrementing error, as well as configurable delays between errors,
+    etc.
+
+    If the retry_strategy iterator itself ends (or is empty to begin
+    with), the function will be called one final time.
+    """
+
+    def _retry_decorator(func: F) -> F:
+        @wraps(func)
+        def retry_wrapper(*args, **kwargs):
+            for i, is_retryable in enumerate(retry_strategy_factory(), start=1):
+                try:
+                    return func(*args, **kwargs)
+                except Exception as ex:
+                    if not is_retryable(ex):
+                        raise ex
+                    getLogger(__name__).info("Retry #%d for %s due to exception %s", i, func, ex)
+            # one final retry that, if it fails, will not get caught and retried.
+            return func(*args, **kwargs)
+
+        return ty.cast(F, retry_wrapper)
+
+    return _retry_decorator
+
+
+def retry_regular(
+    is_retryable: IsRetryable,
+    intervals_factory: ty.Callable[[], ty.Iterable[ty.Any]],
+) -> ty.Callable[[F], F]:
+    return retry(lambda: (is_retryable for _ in intervals_factory()))
+
+
+def retry_sleep(
+    is_retryable: IsRetryable,
+    seconds_iter: ty.Callable[[], ty.Iterable[float]],
+) -> ty.Callable[[F], F]:
+    """E.g. retry_sleep(expo(retries=5)) to get max 6 calls to the function."""
+    return retry_regular(is_retryable, sleep(seconds_iter))
+
+
+def is_exc(*exc_types: ty.Type[Exception]) -> IsRetryable:
+    def _is_exc_retryable(exc: Exception) -> bool:
+        return isinstance(exc, exc_types)
+
+    return _is_exc_retryable

thds/core/generators.py

@@ -0,0 +1,56 @@
+"""Import this module by its name, so that references to things within it are qualified by
+the word 'generators', e.g. generators.sender()
+"""
+import contextlib
+import typing as ty
+
+T = ty.TypeVar("T")
+R = ty.TypeVar("R")
+GEN = ty.TypeVar("GEN", bound=ty.Generator)
+
+
+class return_wrapper(contextlib.AbstractContextManager, ty.Generic[GEN, R]):
+    """Allows you to wrap a generator that accepts and/or yields values,
+    but this will prime the generator and also close it at the end and fetch
+    its return value.
+
+    This will be somewhat easier in 3.13 with the new `gen.close()` behavior.
+    https://discuss.python.org/t/let-generator-close-return-stopiteration-value/24786
+    """
+
+    def __init__(self, gen: GEN):
+        self.gen = gen
+
+    def __enter__(self) -> GEN:
+        next(self.gen)  # prime the generator
+        return self.gen
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        if exc_type is not None:
+            # TODO confirm that this is the correct behavior
+            self.gen.throw(exc_type, exc_value, traceback)
+
+        try:
+            self.gen.throw(GeneratorExit)
+            # equivalent to gen.close() but also gives us StopIteration.value
+        except StopIteration as e:
+            self._return_value = e.value
+
+    @property
+    def return_value(self) -> R:
+        """Only available after the context manager has exited."""
+        return self._return_value
+
+
+def iterator_sender(gen: ty.Generator[ty.Any, T, R], iterator: ty.Iterable[T]) -> R:
+    """This encapsulates the send/close behavior we want in general. See
+    https://discuss.python.org/t/let-generator-close-return-stopiteration-value/24786
+    for how a simple `gen.close()` will do this in 3.13.
+    """
+
+    gen_wrapper: return_wrapper[ty.Generator, R] = return_wrapper(gen)  # type: ignore[arg-type]
+    with gen_wrapper:
+        for i in iterator:
+            gen.send(i)
+
+    return gen_wrapper.return_value

thds/core/git.py

@@ -0,0 +1,81 @@
+# some basic git utilities.
+#
+# All of these will error if git is not available, or if the repo is not present.  The
+# caller is expected to catch subprocess.CalledProcessError as well as FileNotFoundError.
+import os
+import subprocess as sp
+import typing as ty
+
+from . import log
+
+LOGGER = log.getLogger(__name__)
+CALGITVER_NO_SECONDS_FORMAT = "%Y%m%d.%H%M"
+
+
+NO_GIT = (sp.CalledProcessError, FileNotFoundError)
+# FileNotFoundError can happen if git is not installed at all.
+
+
+def _simple_run(s_or_l_cmd: ty.Union[str, ty.List[str]], env=None, cwd=None) -> str:
+    kwargs = dict(text=True, shell=True, env=env, cwd=cwd)
+    if isinstance(s_or_l_cmd, list):
+        kwargs["shell"] = False
+    return sp.check_output(s_or_l_cmd, **kwargs).rstrip("\n")
+
+
+def get_repo_name() -> str:
+    return _simple_run("git remote get-url origin").split("/")[-1].rstrip().split(".")[0]
+
+
+def get_commit_hash() -> str:
+    LOGGER.debug("`get_commit` reading from Git repo.")
+    return _simple_run("git rev-parse --verify HEAD")
+
+
+def is_clean() -> bool:
+    LOGGER.debug("`is_clean` reading from Git repo.")
+    # command will show changes (staged and unstaged) in the working tree since the last commit.
+    # if there are none (i.e the repo is clean), an empty string will be printed
+    # https://git-scm.com/docs/git-diff#Documentation/git-diff.txt-Variouswaystocheckyourworkingtree
+    return "" == _simple_run("git diff HEAD")
+
+
+def get_branch() -> str:
+    LOGGER.debug("`get_branch` reading from Git repo.")
+    return _simple_run("git branch --show-current")
+
+
+def get_commit_datetime_and_hash(
+    *file_patterns: str,
+    cwd: ty.Optional[str] = None,
+    date_format: str = CALGITVER_NO_SECONDS_FORMAT,
+) -> ty.Tuple[str, str]:
+    """Useful for making a CalGitVer from a file or set of matching files.
+
+    If no file patterns were provided, it will return the commit datetime and hash of the
+    most recent commit.
+    """
+    assert " " not in date_format, "date_format cannot contain spaces"
+    dt, hash = (
+        _simple_run(
+            # the space between %cd and %h allows us to split on it
+            f"git log -n 1 --date=format-local:{date_format} --format=format:'%cd %H' -- "
+            + " ".join(file_patterns),
+            env=dict(os.environ, TZ="UTC0"),
+            cwd=cwd,
+        )
+        .strip("'")
+        .split(" ")
+    )
+    return dt, hash
+
+
+def get_merge_base(branch1: str = "", branch2: str = "main") -> str:
+    return _simple_run(f"git merge-base {branch1 or get_branch()} {branch2}")
+
+
+def get_commit_datetime_str(commit_hash: str, date_format: str = CALGITVER_NO_SECONDS_FORMAT) -> str:
+    return _simple_run(
+        f"git log -n 1 --date=format-local:{date_format} --format=format:'%cd' {commit_hash}",
+        env=dict(os.environ, TZ="UTC0"),
+    )

thds/core/hash_cache.py

@@ -0,0 +1,86 @@
+"""Sometimes, you just want to cache hashes. Specifically, hashes of files.
+
+We cache these hashes as files themselves, and the default location is under the user's
+home directory.
+
+The name of the file is an implementation detail that includes the hash of the file path,
+the directory it lives in is the hashlib name of the hash algorithm, and the contents of
+the file are the raw bytes of the hash. However, none of these details is guaranteed to
+remain stable over time, and the only stable interface is the `hash_file` and `filehash`
+functions themselves.
+"""
+
+import hashlib
+import os
+from pathlib import Path
+from typing import Any
+
+from . import config, files
+from .hashing import Hash, hash_using
+from .home import HOMEDIR
+from .log import getLogger
+from .types import StrOrPath
+
+CACHE_HASH_DIR = config.item("directory", HOMEDIR() / ".hash-cache", parse=Path)
+_1GB = 1 * 2**30  # log if hashing a file larger than this, since it will be slow.
+
+
+logger = getLogger(__name__)
+
+
+def _filecachekey(path: Path, hashtype: str) -> Path:
+    # the construction of our cache key here is somewhat arbitrary,
+    # and the name substring is really just for debugging purposes.
+    # however, the filesize is a useful bit of additional 'entropy'
+    # that will help us avoid edge cases that might arise from race
+    # conditions, and the approach must remain stable over time for
+    # the cache to provide a meaningful advantage.
+    path_str = str(path)
+    path_hash = hash_using(path_str.encode(), hashlib.sha256()).hexdigest()
+    # we use a compressed (hashed) version of the path because
+    # filenames can get kind of long and we don't want to deal with
+    # long filenames blowing up our system by being unwritable.
+    return (
+        CACHE_HASH_DIR()
+        / hashtype
+        / (path_str[-50:].replace("/", "|") + "-" + path_hash + "+" + str(path.stat().st_size))
+    )
+
+
+def _is_no_older_than(file: Path, other: Path) -> bool:
+    """Returns True if `file` is no older than `other`. Both files must exist."""
+    return file.stat().st_mtime >= other.stat().st_mtime
+
+
+def hash_file(filepath: StrOrPath, hasher: Any) -> bytes:
+    """Hashes a file with the given hashlib hasher. If we've already previously computed
+    the given hash for the file and the file hasn't changed (according to filesystem
+    mtime) since we stored that hash, we'll just return the cached hash.
+
+    File must exist and respond positively to stat().
+    """
+    resolved_path = Path(filepath).resolve()
+    cached_hash_path = _filecachekey(resolved_path, hasher.name)
+    # now we can check to see if we have hash bytes for that file somewhere already.
+    hash_cached = "hash-cached" if cached_hash_path.exists() else ""
+    if hash_cached and _is_no_older_than(cached_hash_path, resolved_path):
+        logger.debug("Reusing known hash for %s - cache key %s", resolved_path, cached_hash_path)
+        return cached_hash_path.read_bytes()
+
+    psize = resolved_path.stat().st_size
+    if psize > _1GB:
+        log_at_lvl = logger.warning if hash_cached else logger.info
+        # I want to know how often we're finding 'outdated' hashes; those should be rare.
+        log_at_lvl(f"Hashing {psize/_1GB:.2f} GB file at {resolved_path}{hash_cached}")
+
+    hash_bytes = hash_using(resolved_path, hasher).digest()
+    cached_hash_path.parent.mkdir(parents=True, exist_ok=True)
+    with files.atomic_binary_writer(cached_hash_path) as f:
+        f.write(hash_bytes)
+    return hash_bytes
+
+
+def filehash(algo: str, pathlike: os.PathLike) -> Hash:
+    """Wraps a cached hash of a file in a core.hashing.Hash object, which carries the name
+    of the hash algorithm used."""
+    return Hash(algo, hash_file(pathlike, hashlib.new(algo)))

thds/core/hashing.py

@@ -0,0 +1,106 @@
+"""
+https://stackoverflow.com/questions/3431825/generating-an-md5-checksum-of-a-file
+I have written this code too many times to write it again. Why isn't this in the stdlib?
+"""
+import base64
+import contextlib
+import io
+import os
+import threading
+import typing as ty
+from pathlib import Path
+
+# Python threads don't allow for significant CPU parallelism, so
+# allowing for more than a few of these per process is a recipe for
+# getting nothing done.
+_SEMAPHORE = threading.BoundedSemaphore(int(os.getenv("THDS_CORE_HASHING_PARALLELISM", 4)))
+_CHUNK_SIZE = int(os.getenv("THDS_CORE_HASHING_CHUNK_SIZE", 65536))
+# https://stackoverflow.com/questions/17731660/hashlib-optimal-size-of-chunks-to-be-used-in-md5-update
+# this may not apply to us as the architecture is 32 bit, but it's at
+# least a halfway decent guess and benchmarking this ourselves would
+# be a massive waste of time.
+
+T = ty.TypeVar("T")
+SomehowReadable = ty.Union[ty.AnyStr, ty.IO[ty.AnyStr], Path]
+
+
+def hash_readable_chunks(bytes_readable: ty.IO[bytes], hasher: T) -> T:
+    """Return thing you can call .digest or .hexdigest on.
+
+    E.g.:
+
+    hash_readable_chunks(open(Path('foo/bar'), 'rb'), hashlib.sha256()).hexdigest()
+    """
+    with _SEMAPHORE:
+        for chunk in iter(lambda: bytes_readable.read(_CHUNK_SIZE), b""):
+            hasher.update(chunk)  # type: ignore
+        return hasher
+
+
+@contextlib.contextmanager
+def attempt_readable(thing: SomehowReadable) -> ty.Iterator[ty.IO[bytes]]:
+    """Best effort: make this object a bytes-readable."""
+    if hasattr(thing, "read") and hasattr(thing, "seek"):
+        try:
+            yield thing  # type: ignore
+            return
+        finally:
+            thing.seek(0)  # type: ignore
+    elif isinstance(thing, bytes):
+        yield io.BytesIO(thing)
+        return
+    with open(thing, "rb") as readable:  # type: ignore
+        yield readable
+
+
+def hash_using(data: SomehowReadable, hasher: T) -> T:
+    """This is quite dynamic - but if your data object is not readable
+    bytes and is not openable as bytes, you'll get a
+    FileNotFoundError, or possibly a TypeError or other gremlin.
+
+    Therefore, you may pass whatever you want unless it's an actual
+    string - if you want your actual string hashed, you should encode
+    it as actual bytes first.
+    """
+    with attempt_readable(data) as readable:
+        return hash_readable_chunks(readable, hasher)
+
+
+def hash_anything(data: SomehowReadable, hasher: T) -> ty.Optional[T]:
+    try:
+        return hash_using(data, hasher)
+    except (FileNotFoundError, TypeError):
+        # it's unlikely we can operate on this data?
+        return None
+
+
+def b64(digest: bytes) -> str:
+    """The string representation commonly used by Azure utilities.
+
+    We use it in cases where we want to represent the same hash that
+    ADLS will have in UTF-8 string (instead of bytes) format.
+    """
+    return base64.b64encode(digest).decode()
+
+
+def db64(s: str) -> bytes:
+    """Shorthand for the inverse of b64."""
+    return base64.b64decode(s)
+
+
+def _repr_bytes(bs: bytes) -> str:
+    return f"db64('{b64(bs)}')"
+
+
+class Hash(ty.NamedTuple):
+    """Algorithm name needs to match something supported by hashlib.
+
+    A good choice would be sha256. Use md5 if you have to.
+    """
+
+    algo: str
+    # valid algorithm names listed here: https://docs.python.org/3/library/hashlib.html#constructors
+    bytes: bytes
+
+    def __repr__(self) -> str:
+        return f"Hash(algo='{self.algo}', bytes={_repr_bytes(self.bytes)})"

thds/core/home.py

@@ -0,0 +1,15 @@
+import os
+from pathlib import Path
+
+from .config import item
+
+# On our GitHub runners, we can't make hardlinks from /runner/home to where our stuff actually goes.
+# This allows us to use 'a' home directory that is on the same filesystem.
+_RUNNER_WORK = Path("/runner/_work")
+if os.getenv("CI") and _RUNNER_WORK.exists() and _RUNNER_WORK.is_dir():
+    __home = _RUNNER_WORK
+else:
+    __home = Path.home()
+
+
+HOMEDIR = item("thds.core.homedir", parse=Path, default=__home)

thds/core/hostname.py

@@ -0,0 +1,10 @@
+import socket
+
+
+def friendly() -> str:
+    hn = socket.gethostname()
+    if hn.endswith(".local"):
+        hn = hn[: -len(".local")]
+    if hn.startswith("MBP-"):
+        hn = hn[len("MBP-") :]
+    return hn

thds/core/imports.py

@@ -0,0 +1,17 @@
+from importlib import import_module
+from importlib.resources import Package
+
+from .meta import get_base_package
+
+
+def try_imports(*modules: str, module: Package = "", extra: str = "") -> None:
+    try:
+        for m in modules:
+            import_module(m)
+    except ImportError:
+        if extra and module:
+            raise ImportError(
+                f"Install the '{extra}' extra for `{get_base_package(module)}` to use `{module}`."
+            )
+        else:
+            raise ImportError(f"Install {list(modules)}{f' to use `{module}`.' if module else ''}")

thds/core/inspect.py

@@ -0,0 +1,58 @@
+import inspect
+
+import attrs
+
+
+@attrs.frozen
+class CallerInfo:
+    module: str = ""
+    klass: str = ""
+    caller: str = ""
+    line: int = 0
+
+
+def get_caller_info(skip: int = 2) -> CallerInfo:
+    # Credit: https://gist.github.com/lee-pai-long/d3004225e1847b84acb4fbba0c2aea91
+    # I have made some small modifications to the code
+    """Get the name of a caller in the format module.class.method.
+    Copied from: https://gist.github.com/techtonik/2151727
+    :arguments:
+        - skip (integer): Specifies how many levels of stack
+                          to skip while getting caller name.
+                          skip=1 means "who calls me",
+                          skip=2 "who calls my caller" etc.
+    :returns:
+        - module (string): full dotted name of caller module.
+        - klass (string): caller classname if one otherwise None.
+        - caller (string): caller function or method (if a class exist).
+        - line (int): the line of the call.
+        - An empty string is returned if skipped levels exceed stack height.
+    """
+    stack = inspect.stack()
+    start = 0 + skip
+    if len(stack) < start + 1:
+        raise RuntimeError(f"The stack has less than f{skip} + 1 frames in it.")
+    parentframe = stack[start][0]
+
+    # full dotted name of caller module
+    module_info = inspect.getmodule(parentframe)
+    module = module_info.__name__ if module_info else ""
+
+    # class name
+    klass = ""
+    if "self" in parentframe.f_locals:
+        klass = parentframe.f_locals["self"].__class__.__name__
+
+    # method or function name
+    caller = ""
+    if parentframe.f_code.co_name != "<module>":  # top level usually
+        caller = parentframe.f_code.co_name
+
+    # call line
+    line = parentframe.f_lineno
+
+    # Remove reference to frame
+    # See: https://docs.python.org/3/library/inspect.html#the-interpreter-stack
+    del parentframe
+
+    return CallerInfo(module=module, klass=klass, caller=caller, line=line)

thds/core/iterators.py

@@ -0,0 +1,9 @@
+import typing as ty
+
+T = ty.TypeVar("T")
+
+
+def null_safe_iter(it: ty.Optional[ty.Iterable[T]]) -> ty.Iterator[T]:
+    """Iterate the iterable if it is not None"""
+    if it is not None:
+        yield from it