nob.py 0.1.0__py3-none-any.whl

nob/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from nob!"

nob/cli/__init__.py

@@ -0,0 +1,237 @@
+import logging
+from collections.abc import Callable
+from typing import ParamSpec, TypeVar
+
+import rich_click as click
+
+from . import types  # noqa: F401
+from .config import AliasedGroup, CLIMutex, Config, pass_config
+
+all = ["opt", "cmd", "grp", "pass_config", "pass_context", "types"]
+
+P = ParamSpec("P")
+Q = ParamSpec("Q")
+R = TypeVar("R")
+S = TypeVar("S")
+
+
+def __read_config(ctx: click.Context, _, value: str | None):
+    """Callback that is used whenever Config is passed. We use this to always
+    load the correct config. This means that the config is loaded even if the
+    group itself never executes so everything always stays available.
+    """
+    cfg = ctx.ensure_object(Config)
+    cfg.read_config(value)
+    return value
+
+
+def __read_log_file(ctx: click.Context, _, value: str | None):
+    cfg = ctx.ensure_object(Config)
+    if value:
+        cfg.log_file = value
+    return value
+
+
+def __read_verbosity(level: int):
+
+    def callback(ctx: click.Context, _, value: bool):
+        cfg = ctx.ensure_object(Config)
+        if value:
+            cfg.log_level = level
+        return value
+
+    return callback
+
+
+def __install_rich_traceback():
+    import os
+
+    from rich.traceback import install
+
+    DEBUG_TRACE = os.environ.get("DEBUG_TRACE", "0") == "1"
+
+    extra_lines = 3 if DEBUG_TRACE else 0
+    max_frames = 100 if DEBUG_TRACE else 1
+    show_locals = DEBUG_TRACE
+
+    install(
+        show_locals=show_locals,
+        extra_lines=extra_lines,
+        max_frames=max_frames,
+        suppress=["click", "rich"],
+    )
+
+
+def __add_config_options(grp: click.RichGroup | None):
+    return (
+        [
+            click.option(
+                "-v",
+                "--verbose",
+                is_flag=True,
+                help="Enable verbose logging (DEBUG min level).",
+                callback=__read_verbosity(logging.DEBUG),
+                expose_value=False,
+                cls=CLIMutex,
+                not_required_if=["quiet"],
+            ),
+            click.option(
+                "-q",
+                "--quiet",
+                is_flag=True,
+                help="Enable quiet logging (WARNING min level).",
+                callback=__read_verbosity(logging.WARNING),
+                expose_value=False,
+                cls=CLIMutex,
+                not_required_if=["verbose"],
+            ),
+            click.option(
+                "-c",
+                "--config",
+                type=click.Path(exists=True, dir_okay=False),
+                help="Path to a custom config file to load instead of the default (defaults to assets/cfg/default.yml).",
+                callback=__read_config,
+                expose_value=False,
+            ),
+            click.option(
+                "-l",
+                "--log-file",
+                type=click.Path(dir_okay=False),
+                help="Specify the path where the RotatingFileHandler will write its outputs.",
+                callback=__read_log_file,
+                expose_value=False,
+            ),
+        ]
+        if grp is None
+        else []
+    )
+
+
+def __preserve_click_params(func: Callable[P, R], wrapper: Callable[Q, S]):
+    """Modifies the wrapper function in-place to have the same Click parameters as the original function.\\
+    It ensures that the decorators can be used in any order without breaking the underlying Click parameters.
+
+    Args:
+        func (Callable[P, R]): The original function with the correct Click parameters.
+        wrapper (Callable[Q, S]): The wrapper function that needs to have the Click parameters of the original function.
+
+    Returns:
+        Callable[Q, S]: wrapper (so that this function can be nicely chained)
+    """
+    # https://stackoverflow.com/q/57773853#comment101986419_57773853
+    if hasattr(func, "__click_params__"):
+        assert isinstance(func.__click_params__, list)
+        # Actually creates the attribute on the wrapper if it doesn't exist
+        wrapper.__click_params__ = func.__click_params__  # ty:ignore[unresolved-attribute]
+    return wrapper
+
+
+def grp(
+    grp: click.RichGroup | None = None,
+    default: Callable[[], click.RichCommand] | None = None,
+    *default_args,
+    **default_kwargs,
+) -> click.RichGroup:
+    """Registers the decorated function as a Click group and adds the common options to it.\\
+    Please provide default arguments (that don't have defaults defined) since you won't be able to do so in the CLI.
+
+    Args:
+        grp (click.RichGroup, optional): Parent group to attach the group to. Defaults to None.
+        default (() -> RichCommand, optional): Factory of the default command to run if nothing is passed. Defaults to None.
+        *default_args (): Default arguments.
+        **default_kwargs (): Default named arguments.
+    """
+
+    entity = grp or click
+
+    def inner(main: Callable[P, R]):
+        dec = (
+            [
+                entity.group(
+                    name=main.__name__,  # ty:ignore[unresolved-attribute]
+                    help=main.__doc__,
+                    cls=AliasedGroup,
+                    context_settings={"help_option_names": ["-h", "--help"]},
+                    invoke_without_command=default is not None,
+                )
+            ]
+            + __add_config_options(grp)
+            + [
+                click.pass_context,
+            ]
+        )
+
+        def wrapper(ctx: click.Context, *args, **kwargs):
+            if default is not None and ctx.invoked_subcommand is None:
+                ctx.forward(default(), *default_args, **default_kwargs)
+            return main(*args, **kwargs)
+
+        __preserve_click_params(main, wrapper)
+        for d in reversed(dec):
+            wrapper = d(wrapper)
+        return wrapper
+
+    return inner  # ty:ignore[invalid-return-type]
+
+
+def cmd(grp: click.RichGroup | None = None) -> click.RichCommand:
+    """Decorator to create a command. Can be attached to a group.\\
+    Adds the following parameters to the command if they are present in the function signature or if the function accepts `**kwargs`:
+    - `cfg`: The Config object `nob.cli.config.Config`
+    - `ctx`: The Click context object `rich_click.Context`
+    - `lg`: A logger with the name of the command `logging.Logger`
+    """
+    entity = grp or click
+
+    def inner(func: Callable[P, R]):
+        dec = (
+            [
+                entity.command(
+                    name=(name := func.__name__),  # ty:ignore[unresolved-attribute]
+                    help=func.__doc__,
+                    context_settings={"help_option_names": ["-h", "--help"]},
+                ),
+            ]
+            + __add_config_options(grp)
+            + [
+                click.pass_context,
+                pass_config,
+            ]
+        )
+
+        def wrapper(cfg: Config, ctx: click.Context, **kwargs):
+            import inspect
+
+            from nob.logging import init_handler
+
+            lg = logging.getLogger(name)
+            init_handler(cfg.log_level, cfg.log_file)
+
+            sig = inspect.signature(func)
+            has_kwargs = any(p.kind == inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values())
+
+            kw = dict(kwargs)
+            if has_kwargs or "cfg" in sig.parameters:
+                kw["cfg"] = cfg
+            if has_kwargs or "ctx" in sig.parameters:
+                kw["ctx"] = ctx
+            if has_kwargs or "lg" in sig.parameters:
+                kw["lg"] = lg
+
+            return func(**kw)  # ty:ignore[missing-argument]
+
+        __preserve_click_params(func, wrapper)
+        for d in reversed(dec):
+            wrapper = d(wrapper)
+        return wrapper
+
+    __install_rich_traceback()
+    return inner  # ty:ignore[invalid-return-type]
+
+
+opt = click.option
+arg = click.argument
+
+
+def pass_context(func):
+    return click.pass_context(func)

nob/cli/config.py

@@ -0,0 +1,103 @@
+import logging
+import os
+from typing import Any
+
+import rich_click as click
+import yaml
+from pydantic import BaseModel, Field
+from typing_extensions import override
+
+__all__ = ["AliasedGroup", "Config", "pass_config", "CLIMutex"]
+
+
+class Config(BaseModel):
+    """The config."""
+
+    DEFAULT_CONFIG_PATH: str = os.path.join("assets", "cfg", "default.yml")
+
+    aliases: dict[str, str] = Field(default_factory=dict)
+    log_level: int = logging.INFO
+    log_file: str | None = None
+
+    def add_alias(self, alias: str, cmd: str):
+        self.aliases[alias] = cmd
+
+    def read_config(self, filename: str | None):
+        try:
+            with open(self.DEFAULT_CONFIG_PATH) as f:
+                config_data: dict[str, Any] = yaml.safe_load(f) or {}
+        except FileNotFoundError:
+            config_data = {}
+        if filename and os.path.abspath(filename) != os.path.abspath(self.DEFAULT_CONFIG_PATH):
+            with open(filename) as f:
+                user_config = yaml.safe_load(f)
+                if user_config:
+                    config_data.update(user_config)
+
+        if not config_data:
+            return
+
+        # aliases
+        self.aliases.update(config_data.get("aliases", {}))
+
+        # options
+        options: dict[str, Any] = config_data.get("options", {})  # noqa: F841
+
+
+pass_config = click.make_pass_decorator(Config, ensure=True)
+
+
+class AliasedGroup(click.RichGroup):
+    """Aliased rich-click.Group"""
+
+    @override
+    def get_command(self, ctx, cmd_name):
+        rv = click.Group.get_command(self, ctx, cmd_name)
+        if rv is not None:
+            return rv
+
+        cfg = ctx.ensure_object(Config)
+
+        if cmd_name in cfg.aliases:
+            actual_cmd = cfg.aliases[cmd_name]
+            return click.Group.get_command(self, ctx, actual_cmd)
+
+        matches = [x for x in self.list_commands(ctx) if x.lower().startswith(cmd_name.lower())]
+        if not matches:
+            return None
+        elif len(matches) == 1:
+            return click.Group.get_command(self, ctx, matches[0])
+        ctx.fail(f"Too many matches: {', '.join(sorted(matches))}")
+
+    @override
+    def resolve_command(self, ctx, args):
+        _, cmd, args = super().resolve_command(ctx, args)
+        assert cmd is not None
+        return cmd.name, cmd, args
+
+
+class CLIMutex(click.Option):
+    def __init__(self, *args, **kwargs):
+        self.not_required_if: list = kwargs.pop("not_required_if")
+
+        assert self.not_required_if, "'not_required_if' parameter required"
+        help = f"{h} " if (h := kwargs.get("help", "")) else ""
+        kwargs["help"] = f"{help}Mutually exclusive with {', '.join(self.not_required_if)}.".strip()
+        super().__init__(*args, **kwargs)
+
+    @override
+    def handle_parse_result(self, ctx, opts, args):
+        current_opt: bool = self.name in opts
+        for mutex_opt in self.not_required_if:
+            if mutex_opt in opts:
+                if current_opt:
+                    raise click.UsageError(
+                        "Illegal usage: '"
+                        + str(self.name)
+                        + "' is mutually exclusive with "
+                        + str(mutex_opt)
+                        + "."
+                    )
+                else:
+                    self.prompt = None
+        return super().handle_parse_result(ctx, opts, args)

nob/cli/types.py

@@ -0,0 +1 @@
+from rich_click import Choice, File, FloatRange, IntRange, ParamType, Path  # noqa: F401

nob/human/__init__.py

@@ -0,0 +1,60 @@
+from .count import HumanCount
+from .duration import HumanDuration
+from .features import FEATURES
+from .throughput import HumanThroughput
+
+__all__ = ["FEATURES", "count", "duration", "throughput"]
+# revival of https://github.com/rsalmei/about-time and pending PRs
+
+
+def count(value: int | float, unit: str = ""):
+    """Get a renderable human-friendly representation of a count.
+
+    Args:
+        value (int | float): The count value to be represented in a human-friendly format. Must be a non-negative integer or float.
+        unit (str, optional): The unit of the count. Defaults to "".
+
+    Returns:
+        HumanCount: A human-friendly representation of the count.
+
+    Example:
+        >>> from nob import human
+        >>> print(human.count(123456789))
+        123.46M
+    """
+    return HumanCount(value, unit)
+
+
+def duration(value: int | float):
+    """Get a renderable human-friendly representation of a duration in seconds.
+
+    Args:
+        value (int | float): The duration value in seconds to be represented in a human-friendly format. Must be a non-negative integer or float.
+
+    Returns:
+        HumanDuration: A human-friendly representation of the duration.
+
+    Example:
+        >>> from nob import human
+        >>> print(human.duration(123.456))
+        2:03.5
+    """
+    return HumanDuration(value)
+
+
+def throughput(value: int | float, unit: str = "it"):
+    """Get a renderable human-friendly representation of a throughput in units per second.
+
+    Args:
+        value (int | float): The throughput value in units per second to be represented in a human-friendly format. Must be a non-negative integer or float.
+        unit (str, optional): The unit of the throughput. Defaults to "it".
+
+    Returns:
+        HumanThroughput: A human-friendly representation of the throughput.
+
+    Example:
+        >>> from nob import human
+        >>> print(human.throughput(0.123))
+        7.4it/m
+    """
+    return HumanThroughput(value, unit)

nob/human/count.py

@@ -0,0 +1,50 @@
+from typing_extensions import override
+
+from .features import FEATURES, HumanWithUnit, conv_space
+
+__all__ = ["HumanCount"]
+
+SI_1000_SPEC = ("", "k", "M", "G", "T", "P", "E", "Z", "Y")
+SI_1024_SPEC = ("", "K", "M", "G", "T", "P", "E", "Z", "Y")
+IEC_1024_SPEC = ("", "Ki", "Mi", "Gi", "Ti", "Pi", "Ei", "Zi", "Yi")
+DECIMALS = [1, 1, 1, 2, 2, 2, 2, 2, 2]
+
+
+def __human_count(val: float, unit: str, prec: int | None, space: str, divisor: int, spec: tuple) -> str:
+    for scale, dec in zip(spec, DECIMALS, strict=True):  # noqa: B007
+        r = round(val, dec)
+        if r >= divisor:
+            val /= divisor
+            continue
+        break
+    else:
+        r, scale = val, "+"
+
+    if prec is not None:
+        r = round(val, prec)
+    elif r % 1.0 == 0.0:
+        prec = 0
+    elif (r * 10.0) % 1.0 == 0.0:
+        prec = 1
+    else:
+        prec = 2
+    return "{:.{}f}{}{}{}".format(r, prec, space, scale, unit)
+
+
+def fn_human_count(show_space: bool, d1024: bool, iec: bool):
+    def run(val: float, unit: str, prec: int | None = None):
+        return __human_count(val, unit, prec, space, divisor, spec)
+
+    space = conv_space(show_space)
+    divisor, spec = 1024, IEC_1024_SPEC
+    if not iec:
+        divisor, spec = 1024 if d1024 else 1000, SI_1000_SPEC
+    return run
+
+
+class HumanCount(HumanWithUnit):
+    @override
+    def str(self, prec: int | None = None) -> str:
+        return fn_human_count(FEATURES.feature_space, FEATURES.feature_1024, FEATURES.feature_iec)(
+            self.value, self.unit, prec
+        )

nob/human/duration.py

@@ -0,0 +1,62 @@
+from typing_extensions import override
+
+from .features import FEATURES, Human, conv_space
+
+__all__ = ["HumanDuration"]
+
+SPEC = (
+    (1e3, 1e3, "ns", 1),
+    (1e3, 1e3, "µs", 1),  # uses non-ASCII “µs” suffix.
+    (1e3, 1e3, "ms", 1),
+    (60.0, 1.0, "s", 2),
+    # 1:01.1 (minutes in code, 1 decimal).
+    # 1:01:01 (hours in code, 0 decimal).
+)
+
+
+def __human_duration(val: float, prec: int | None, space: str) -> str:
+    val *= 1e9
+    for size, div_next, scale, dec in SPEC:
+        r = round(val, dec)
+        if r >= size:
+            val /= div_next
+            continue
+
+        if prec is not None:
+            r = round(val, prec)
+        elif r % 1.0 == 0.0:
+            prec = 0
+        elif (r * 10.0) % 1.0 == 0.0:
+            prec = 1
+        else:
+            prec = 2
+        return "{:.{}f}{}{}".format(r, prec, space, scale)
+
+    val = round(val, 1)
+    m = val / 60.0
+    if m < 60.0:
+        r = val % 60.0
+        if prec is not None:
+            pass
+        elif r % 1.0 == 0.0:
+            prec = 0
+
+        if prec == 0:
+            return "{:.0f}:{:02.0f}".format(m // 1.0, r)
+        return "{:.0f}:{:04.1f}".format(m // 1.0, round(r, 1))
+
+    return "{:.0f}:{:02.0f}:{:02.0f}".format(m / 60.0 // 1.0, m % 60.0 // 1.0, val % 60.0 // 1.0)
+
+
+def fn_human_duration(show_space: bool):
+    def run(val, prec: int | None = None):
+        return __human_duration(val, prec, space)
+
+    space = conv_space(show_space)
+    return run
+
+
+class HumanDuration(Human):
+    @override
+    def str(self, prec: int | None = None) -> str:
+        return fn_human_duration(FEATURES.feature_space)(self.value, prec)

nob/human/features/__init__.py

@@ -0,0 +1,86 @@
+from abc import ABC, abstractmethod
+
+
+class Features:
+    def __init__(self):
+        self._feature_space = False
+        self._feature_1024 = False
+        self._feature_iec = False
+
+    @property
+    def feature_space(self) -> bool:
+        return self._feature_space
+
+    @property
+    def feature_1024(self) -> bool:
+        return self._feature_1024
+
+    @property
+    def feature_iec(self) -> bool:
+        return self._feature_iec
+
+    @feature_space.setter
+    def feature_space(self, value: bool):
+        self._feature_space = bool(value)
+
+    @feature_1024.setter
+    def feature_1024(self, value: bool):
+        self._feature_1024 = bool(value)
+
+    @feature_iec.setter
+    def feature_iec(self, value: bool):
+        self._feature_iec = bool(value)
+        self.feature_1024 = value
+
+
+def conv_space(space: bool) -> str:
+    return " " if space else ""
+
+
+FEATURES = Features()
+
+
+class Human(ABC):
+    def __init__(self, value: int | float):
+        assert value >= 0.0
+        self.__value = value
+
+    @property
+    def value(self):
+        return self.__value
+
+    @abstractmethod
+    def str(self, prec: int | None = None) -> str:
+        """Return a human-friendly representation of the value. It dynamically calculates the best scale to use.\\
+        You don't need to call this method directly, just use `str()` or `print()` on the object.
+
+        Args:
+            prec: an optional custom precision to use in the representation. Defaults to None.
+
+        Returns:
+            str: A human-friendly representation of the value.
+        """
+        pass
+
+    def __str__(self):
+        return self.str()
+
+    def __repr__(self):
+        return "{}{{ value={} }} -> {}".format(self.__class__.__name__, self.__value, self)
+
+    def __eq__(self, other):
+        return self.__str__() == other
+
+
+class HumanWithUnit(Human):
+    def __init__(self, value: int | float, unit: str = ""):
+        super().__init__(value)
+        self.__unit = unit
+
+    @property
+    def unit(self) -> str:
+        return self.__unit
+
+    def with_unit(self, value: str):
+        """Return a new instance of the same class with the same value but a different unit."""
+        return self.__class__(self.value, value)

nob/human/throughput.py

@@ -0,0 +1,52 @@
+from typing_extensions import override
+
+from .count import fn_human_count
+from .features import FEATURES, HumanWithUnit, conv_space
+
+__all__ = ["HumanThroughput"]
+
+
+SPEC = (
+    (24.0, "/d", 2),
+    (60.0, "/h", 1),
+    (60.0, "/m", 1),
+    # "/s" in code.
+)
+
+
+def __human_throughput(val: float, unit: str, prec: int | None, space: str, fn_count) -> str:
+    val *= 60.0 * 60.0 * 24.0
+    for size, scale, dec in SPEC:
+        r = round(val, dec)
+        if r >= size:
+            val /= size
+            continue
+
+        if prec is not None:
+            r = round(val, prec)
+        elif r % 1.0 == 0.0:
+            prec = 0
+        elif (r * 10.0) % 1.0 == 0.0:
+            prec = 1
+        else:
+            prec = 2
+        return "{:.{}f}{}{}{}".format(r, prec, space, unit, scale)
+
+    return "{}/s".format(fn_count(val, unit, prec))
+
+
+def fn_human_throughput(show_space: bool, d1024: bool, iec: bool):
+    def run(val: float, unit: str, prec: int | None = None):
+        return __human_throughput(val, unit, prec, space, fn_count)
+
+    fn_count = fn_human_count(show_space, d1024, iec)
+    space = conv_space(show_space)
+    return run
+
+
+class HumanThroughput(HumanWithUnit):
+    @override
+    def str(self, prec: int | None = None) -> str:
+        return fn_human_throughput(FEATURES.feature_space, FEATURES.feature_1024, FEATURES.feature_iec)(
+            self.value, self.unit, prec
+        )

nob/ipc/__init__.py

@@ -0,0 +1 @@
+from .named_semaphore import *