btx-lib-mail 1.0.0__py3-none-any.whl

btx_lib_mail/__init__.py

@@ -0,0 +1,24 @@
+"""Public package surface exposing greeting, failure, and metadata hooks."""
+
+from __future__ import annotations
+
+from .behaviors import (
+    CANONICAL_GREETING,
+    emit_greeting,
+    noop_main,
+    raise_intentional_failure,
+)
+from .lib_mail import ConfMail, conf, logger, send
+from .__init__conf__ import print_info
+
+__all__ = [
+    "CANONICAL_GREETING",
+    "emit_greeting",
+    "noop_main",
+    "print_info",
+    "raise_intentional_failure",
+    "ConfMail",
+    "conf",
+    "send",
+    "logger",
+]

btx_lib_mail/__init__conf__.py

@@ -0,0 +1,67 @@
+"""Static package metadata surfaced to CLI commands and documentation.
+
+Purpose
+-------
+Expose the current project metadata as simple constants. These values are kept
+in sync with ``pyproject.toml`` by development automation (tests, push
+pipelines), so runtime code does not query packaging metadata.
+
+Contents
+--------
+* Module-level constants describing the published package.
+* :func:`print_info` rendering the constants for the CLI ``info`` command.
+
+System Role
+-----------
+Lives in the adapters/platform layer; CLI transports import these constants to
+present authoritative project information without invoking packaging APIs.
+"""
+
+from __future__ import annotations
+
+#: Distribution name declared in ``pyproject.toml``.
+name = "btx_lib_mail"
+#: Human-readable summary shown in CLI help output.
+title = "Template for python apps with registered cli commands"
+#: Current release version pulled from ``pyproject.toml`` by automation.
+version = "1.0.0"
+#: Repository homepage presented to users.
+homepage = "https://github.com/bitranox/btx_lib_mail"
+#: Author attribution surfaced in CLI output.
+author = "bitranox"
+#: Contact email surfaced in CLI output.
+author_email = "bitranox@gmail.com"
+#: Console-script name published by the package.
+shell_command = "btx-lib-mail"
+
+
+def print_info() -> None:
+    """Print the summarised metadata block used by the CLI ``info`` command.
+
+    Why
+        Provides a single, auditable rendering function so documentation and
+        CLI output always match the system design reference.
+
+    Side Effects
+        Writes to ``stdout``.
+
+    Examples
+    --------
+    >>> print_info()  # doctest: +ELLIPSIS
+    Info for btx_lib_mail:
+    ...
+    """
+
+    fields = [
+        ("name", name),
+        ("title", title),
+        ("version", version),
+        ("homepage", homepage),
+        ("author", author),
+        ("author_email", author_email),
+        ("shell_command", shell_command),
+    ]
+    pad = max(len(label) for label, _ in fields)
+    lines = [f"Info for {name}:", ""]
+    lines.extend(f"    {label.ljust(pad)} = {value}" for label, value in fields)
+    print("\n".join(lines))

btx_lib_mail/__main__.py

@@ -0,0 +1,92 @@
+"""## btx_lib_mail.__main__ {#module-btx-lib-mail-main}
+
+**Purpose:** Provide the `python -m btx_lib_mail` entry point mandated by the
+packaging guidelines, delegating to `btx_lib_mail.cli.main` so exit semantics
+remain identical to the console script.
+
+**Contents:** `_open_cli_session`, `_command_to_run`, `_command_name`, and
+`_module_main` — the helpers that compose module execution with
+`lib_cli_exit_tools`.
+
+**System Role:** Mirrors the description in
+`docs/systemdesign/module_reference.md#module-main-session-helpers`, ensuring
+module execution shares the same traceback limits and command wiring as the CLI.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from contextlib import AbstractContextManager
+from typing import Final
+
+from lib_cli_exit_tools import cli_session
+import rich_click as click
+
+from . import __init__conf__, cli
+
+TRACEBACK_SUMMARY_LIMIT: Final[int] = cli.TRACEBACK_SUMMARY_LIMIT
+"""Character budget for truncated tracebacks when running via module entry."""
+TRACEBACK_VERBOSE_LIMIT: Final[int] = cli.TRACEBACK_VERBOSE_LIMIT
+"""Character budget for verbose tracebacks when running via module entry."""
+
+
+CommandRunner = Callable[..., int]
+
+
+def _open_cli_session() -> AbstractContextManager[CommandRunner]:
+    """### _open_cli_session() -> AbstractContextManager[CommandRunner] {#module-main-open-cli-session}
+
+    **Purpose:** Provide a context manager wired with the agreed traceback
+    limits so module execution mirrors the CLI.
+
+    **Returns:** Context manager yielding the callable that invokes the Click
+    command via `lib_cli_exit_tools.cli_session`.
+    """
+
+    return cli_session(
+        summary_limit=TRACEBACK_SUMMARY_LIMIT,
+        verbose_limit=TRACEBACK_VERBOSE_LIMIT,
+    )
+
+
+def _command_to_run() -> click.Command:
+    """### _command_to_run() -> click.Command {#module-main-command-to-run}
+
+    **Purpose:** Identify the root Click command used by module execution.
+
+    **Returns:** `click.Command` referencing `btx_lib_mail.cli.cli`.
+    """
+
+    return cli.cli
+
+
+def _command_name() -> str:
+    """### _command_name() -> str {#module-main-command-name}
+
+    **Purpose:** Provide the console-script name announced by the session so
+    tests can assert against a single source of truth.
+
+    **Returns:** `str` containing `__init__conf__.shell_command`.
+    """
+
+    return __init__conf__.shell_command
+
+
+def _module_main() -> int:
+    """### _module_main() -> int {#module-main-module-main}
+
+    **Purpose:** Implement `python -m btx_lib_mail` by delegating to the CLI
+    while preserving traceback limits.
+
+    **Returns:** `int` exit code produced by the CLI run.
+    """
+
+    with _open_cli_session() as runner:
+        return runner(
+            _command_to_run(),
+            prog_name=_command_name(),
+        )
+
+
+if __name__ == "__main__":
+    raise SystemExit(_module_main())

btx_lib_mail/behaviors.py

@@ -0,0 +1,133 @@
+"""## btx_lib_mail.behaviors {#module-btx-lib-mail-behaviors}
+
+**Purpose:** Gather the domain-placeholder helpers that back the CLI scaffold so
+each behaviour has a single, well-documented home. Keeping the trio together
+lets adapter layers evolve without rewriting domain stubs.
+
+**Contents:**
+- `emit_greeting` — success-path helper that emits the canonical message.
+- `raise_intentional_failure` — deterministic failure hook for exercising error paths.
+- `noop_main` — placeholder entry point for transports expecting a `main`.
+
+**System Role:** Described in
+`docs/systemdesign/module_reference.md#feature-cli-behavior-scaffold`; this
+module represents the current domain surface for the template while richer
+features incubate elsewhere.
+"""
+
+from __future__ import annotations
+
+from typing import Final, TextIO
+
+import sys
+
+
+CANONICAL_GREETING: Final[str] = "Hello World"
+"""Canonical greeting line shared across CLI and smoke tests."""
+
+
+def _target_stream(preferred: TextIO | None) -> TextIO:
+    """Return the stream that should hear the greeting."""
+
+    return preferred if preferred is not None else sys.stdout
+
+
+def _greeting_line() -> str:
+    """Return the greeting exactly as it should appear."""
+
+    return f"{CANONICAL_GREETING}\n"
+
+
+def _flush_if_possible(stream: TextIO) -> None:
+    """Flush the stream when the stream knows how to flush."""
+
+    flush = getattr(stream, "flush", None)
+    if callable(flush):
+        flush()
+
+
+def emit_greeting(*, stream: TextIO | None = None) -> None:
+    """### emit_greeting(stream: TextIO | None = None) {#behaviors-emit-greeting}
+
+    **Purpose:** Offer a deterministic success story that documentation, tests,
+    and CLI commands can reuse while the real domain behaviour is still under
+    construction.
+
+    **What:** Writes `CANONICAL_GREETING` followed by a newline to the selected
+    text stream and flushes the stream when a `flush` method exists.
+
+    **Parameters:**
+    - `stream: TextIO | None = None` — Optional destination. When `None`, the
+      helper targets `sys.stdout`.
+
+    **Returns:** `None`.
+
+    **Raises:** No new exceptions are raised; any stream failures bubble up.
+
+    **Example:**
+    >>> from io import StringIO
+    >>> buffer = StringIO()
+    >>> emit_greeting(stream=buffer)
+    >>> buffer.getvalue()
+    'Hello World\\n'
+    """
+
+    target = _target_stream(stream)
+    target.write(_greeting_line())
+    _flush_if_possible(target)
+
+
+def raise_intentional_failure() -> None:
+    """### raise_intentional_failure() {#behaviors-raise-intentional-failure}
+
+    **Purpose:** Provide a guaranteed failure hook so transports and tests can
+    assert traceback and exit-code behaviour without introducing ad-hoc errors.
+
+    **What:** Always raises `RuntimeError('I should fail')`.
+
+    **Parameters:** None.
+
+    **Returns:** This helper never returns.
+
+    **Raises:** `RuntimeError` — unconditionally, with the canonical message.
+
+    **Example:**
+    >>> try:
+    ...     raise_intentional_failure()
+    ... except RuntimeError as exc:
+    ...     exc.args[0]
+    'I should fail'
+    """
+
+    raise RuntimeError("I should fail")
+
+
+def noop_main() -> None:
+    """### noop_main() {#behaviors-noop-main}
+
+    **Purpose:** Honour tooling contracts that expect a `main` callable even
+    while the real domain implementation is pending.
+
+    **What:** Performs no work and returns immediately so callers can treat the
+    placeholder as a benign default.
+
+    **Parameters:** None.
+
+    **Returns:** `None`.
+
+    **Raises:** No exceptions.
+
+    **Example:**
+    >>> noop_main() is None
+    True
+    """
+
+    return None
+
+
+__all__ = [
+    "CANONICAL_GREETING",
+    "emit_greeting",
+    "raise_intentional_failure",
+    "noop_main",
+]