From 70b663992c755ddd2f0fd675e1e3e0d3aad2f9d4 Mon Sep 17 00:00:00 2001
From: goodboy <goodboy_foss@protonmail.com>
Date: Fri, 20 Feb 2026 15:05:45 -0500
Subject: [PATCH] Better doc-strings n styling in `piker.cli` eps

Add comprehensive docstrings to the top-level CLI endpoints and helpers,
explaining the purpose and structure of each (sub)command.

Deats,
- add detailed docstring to `pikerd()` explaining its role as the
  root service-actor/daemon supervisor.
- add docstring to `cli()` noting it's the root endpoint generally
  requiring a sub-cmd input.
- add extensive docstring to `services()` explaining the daemon naming
  conventions and listing a few current/common service actors.
- add docstring to `_load_clis()` explaining dynamic CLI loading.

Stylin,
- add multiline style to `and not maddrs` conditional in
  `load_trans_eps()`.
- drop commented-out `--tsdb` and `--es` click options from
  `pikerd()`, they're more or less obsolete given `nativedb`.
- add type annots where obviously handy.
- add TODO comment about UDS support in `services()`.

(this commit msg was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
---
 piker/cli/__init__.py | 79 ++++++++++++++++++++++++++++++++-----------
 1 file changed, 59 insertions(+), 20 deletions(-)

diff --git a/piker/cli/__init__.py b/piker/cli/__init__.py
index 5a4d3c99..f469242e 100644
--- a/piker/cli/__init__.py
+++ b/piker/cli/__init__.py
@@ -61,7 +61,8 @@ def load_trans_eps(
 
     if (
         network
-        and not maddrs
+        and
+        not maddrs
     ):
         # load network section and (attempt to) connect all endpoints
         # which are reachable B)
@@ -112,26 +113,19 @@ def load_trans_eps(
     default=None,
     help='Multiaddrs to bind or contact',
 )
-# @click.option(
-#     '--tsdb',
-#     is_flag=True,
-#     help='Enable local ``marketstore`` instance'
-# )
-# @click.option(
-#     '--es',
-#     is_flag=True,
-#     help='Enable local ``elasticsearch`` instance'
-# )
 def pikerd(
     maddr: list[str] | None,
     loglevel: str,
     tl: bool,
     pdb: bool,
-    # tsdb: bool,
-    # es: bool,
 ):
     '''
-    Spawn the piker broker-daemon.
+    Start the "root service actor", `pikerd`, run it until
+    cancellation.
+
+    This "root daemon" operates as the top most service-mngr and
+    subsys-as-subactor supervisor, think of it as the "init proc" of
+    any of any `piker` application or daemon-process tree.
 
     '''
     # from tractor.devx import maybe_open_crash_handler
@@ -240,6 +234,14 @@ def cli(
     regaddr: str,
 
 ) -> None:
+    '''
+    The "root" `piker`-cmd CLI endpoint.
+
+    NOTE, this def generally relies on and requires a sub-cmd to be
+    provided by the user, OW only a `--help` msg (listing said
+    subcmds) will be dumped to console.
+
+    '''
     if configdir is not None:
         assert os.path.isdir(configdir), f"`{configdir}` is not a valid path"
         config._override_config_dir(configdir)
@@ -301,18 +303,47 @@ def cli(
 def services(
     config,
     tl: bool,
-    ports,
+    ports: list[int],
 ):
+    '''
+    List all `piker` "service deamons" to the console in
+    a `json`-table which maps each actor's UID in the form,
 
-    from ..service import (
+    `{service_name}.{subservice_name}.{UUID}`
+
+    to its (primary) IPC server address.
+
+    (^TODO, should be its multiaddr form once we support it)
+
+    Note that by convention actors which operate as "headless"
+    processes (those without GUIs/graphics, and which generally
+    parent some noteworthy subsystem) are normally suffixed by
+    a "d" such as,
+
+    - pikerd: the root runtime supervisor
+    - brokerd: a broker-backend order ctl daemon
+    - emsd: the internal dark-clearing and order routing daemon
+    - datad: a data-provider-backend data feed daemon
+    - samplerd: the real-time data sampling and clock-syncing daemon
+
+    "Headed units" are normally just given an obvious app-like name
+    with subactors indexed by `.` such as,
+    - chart: the primary modal charting iface, a Qt app
+    - chart.fsp_0: a financial-sig-proc cascade instance which
+                   delivers graphics to a parent `chart` app.
+    - polars_boi: some (presumably) `polars` using console app.
+
+    '''
+    from piker.service import (
         open_piker_runtime,
         _default_registry_port,
         _default_registry_host,
     )
 
-    host = _default_registry_host
+    # !TODO, mk this to work with UDS!
+    host: str = _default_registry_host
     if not ports:
-        ports = [_default_registry_port]
+        ports: list[int] = [_default_registry_port]
 
     addr = tractor._addr.wrap_address(
         addr=(host, ports[0])
@@ -347,7 +378,15 @@ def services(
 
 
 def _load_clis() -> None:
-    # from ..service import elastic  # noqa
+    '''
+    Dynamically load and register all subsys CLI endpoints (at call
+    time).
+
+    NOTE, obviously this is normally expected to be called at
+    `import` time and implicitly relies on our use of various
+    `click`/`typer` decorator APIs.
+
+    '''
     from ..brokers import cli  # noqa
     from ..ui import cli  # noqa
     from ..watchlists import cli  # noqa
@@ -357,5 +396,5 @@ def _load_clis() -> None:
     from ..accounting import cli  # noqa
 
 
-# load downstream cli modules
+# load all subsytem cli eps
 _load_clis()