Rework CLI interface

.github/workflows/pythonpackage.yml

@@ -3,7 +3,7 @@ name: Python package
 on: [push, pull_request, workflow_dispatch]
 
 env:
-  release-python-version: "3.10"
+  release-python-version: "3.11"
 
 jobs:
   test:
@@ -81,7 +81,7 @@ jobs:
           name: distribution-packages
           path: dist/
       - name: Publish a Python distribution to PyPI
-        uses: pypa/gh-action-pypi-publish@master
+        uses: pypa/gh-action-pypi-publish@release/v1
         with:
           user: __token__
           password: ${{ secrets.pypi_password }}

MANIFEST.in

@@ -28,3 +28,5 @@ exclude .gitmodules
 exclude .pre-commit-config.yaml
 exclude .github_changelog_generator
 exclude .dockerignore
+
+prune docs/_build

docs/api/cli.rst

@@ -17,11 +17,11 @@ Decorators
 ----------
 
 .. automodule:: metricq.cli.decorator
-    :members: metricq_command, metricq_metric_option, metricq_server_option, metricq_syslog_option, metricq_token_option,
+    :members: command, metric_option, server_option, syslog_option, token_option,
 
 
-Parameter
----------
+Parameters
+----------
 For you convenience, we provide a set of custom parameter types that you can use as custom types in your click option definitions.
 
 .. automodule:: metricq.cli.params

docs/conf.py

@@ -42,7 +42,7 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
     "dateutil": ("https://dateutil.readthedocs.io/en/stable/", None),
-    "aio_pika": ("https://aio-pika.readthedocs.io/en/latest/", None),
+    "aio_pika": ("https://docs.aio-pika.com/", None),
 }
 
 

docs/howto/project-structure.rst

@@ -196,11 +196,11 @@ code at runtime:
 
 .. code-block:: toml
 
-    # in pythonproject.toml
+    # in pyproject.toml
 
     [build-system]
     requires = [
-        ..., # other build dependencies here
+        # ..., other build dependencies here
         "setuptools_scm[toml]~=6.0",
     ]
 

docs/upgrading.rst

@@ -190,3 +190,19 @@ Renaming of setup.py options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The user option ``out-dir`` has been renamed to ``package-dir``.
+
+`5.x` → `6.0`
+-------------
+
+Renaming of CLI decorators
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The docorators of the CLI feature have been renamed.
+
+- `metricq_syslog_option` -> :func:`cli.decorator.syslog_option`
+- `metricq_server_option` -> :func:`cli.decorator.server_option`
+- `metricq_token_option` -> :func:`cli.decorator.token_option`
+- `metricq_metric_option` -> :func:`cli.decorator.metric_option`
+- `metricq_command` -> :func:`cli.decorator.command`
+
+

examples/metricq_client.py

@@ -44,7 +44,6 @@
 import aiomonitor  # type: ignore
 
 import metricq
-from metricq.cli import metricq_command
 
 logger = metricq.get_logger()
 
@@ -59,7 +58,7 @@ async def run(server: str, token: str) -> None:
             await client.stopped()
 
 
-@metricq_command(default_token="client-py-example")
+@metricq.cli.command(default_token="client-py-example")
 def main(server: str, token: str) -> None:
     asyncio.run(run(server, token))
 

examples/metricq_get_history.py

@@ -34,11 +34,8 @@
 import click
 
 import metricq
-from metricq.cli import metricq_command
-from metricq.cli.decorator import metricq_metric_option
-from metricq.logging import get_logger
 
-logger = get_logger()
+logger = metricq.get_logger()
 
 
 async def aget_history(
@@ -91,8 +88,8 @@ async def aget_history(
             click.echo(aggregate)
 
 
-@metricq_command(default_token="history-py-dummy")
-@metricq_metric_option()
+@metricq.cli.command(default_token="history-py-dummy")
+@metricq.cli.metric_option()
 @click.option("--list-metrics", is_flag=True)
 @click.option("--list-metadata", is_flag=True)
 def get_history(

examples/metricq_get_history_raw.py

@@ -33,8 +33,6 @@
 import click
 
 import metricq
-from metricq.cli import metricq_command
-from metricq.cli.decorator import metricq_metric_option
 from metricq.history_client import HistoryRequestType
 
 
@@ -73,8 +71,8 @@ async def aget_history(server: str, token: str, metric: str) -> None:
     await client.stop(None)
 
 
-@metricq_command(default_token="history-py-dummy")
-@metricq_metric_option()
+@metricq.cli.command(default_token="history-py-dummy")
+@metricq.cli.metric_option()
 def get_history(server: str, token: str, metric: str) -> None:
     asyncio.run(aget_history(server, token, metric))
 

examples/metricq_pandas.py

@@ -33,8 +33,6 @@
 import click
 
 import metricq
-from metricq.cli import metricq_command
-from metricq.cli.decorator import metricq_metric_option
 from metricq.pandas import PandasHistoryClient
 
 logger = metricq.get_logger()
@@ -73,8 +71,8 @@ async def aget_history(server: str, token: str, metric: str) -> None:
         click.echo("----------")
 
 
-@metricq_command(default_token="history-py-dummy")
-@metricq_metric_option(default="example.quantity")
+@metricq.cli.command(default_token="history-py-dummy")
+@metricq.cli.metric_option(default="example.quantity")
 def get_history(server: str, token: str, metric: str) -> None:
     asyncio.run(aget_history(server, token, metric))
 

examples/metricq_sink.py

@@ -33,11 +33,8 @@
 
 import metricq
 from metricq import Metric
-from metricq.cli import metricq_command
-from metricq.cli.decorator import metricq_metric_option
-from metricq.logging import get_logger
 
-logger = get_logger()
+logger = metricq.get_logger()
 
 
 # To implement a MetricQ Sink, subclass metricq.Sink
@@ -70,8 +67,8 @@ async def on_data(
         )
 
 
-@metricq_command(default_token="sink-py-dummy")
-@metricq_metric_option(multiple=True)
+@metricq.cli.command(default_token="sink-py-dummy")
+@metricq.cli.metric_option(multiple=True)
 def source(server: str, token: str, metric: list[Metric]) -> None:
     # Initialize the DummySink class with a list of metrics given on the
     # command line.

examples/metricq_source.py

@@ -31,10 +31,8 @@
 from typing import Any
 
 import metricq
-from metricq.cli import metricq_command
-from metricq.logging import get_logger
 
-logger = get_logger()
+logger = metricq.get_logger()
 
 
 class DummySource(metricq.IntervalSource):
@@ -65,7 +63,7 @@ async def update(self) -> None:
         )
 
 
-@metricq_command(default_token="source-py-dummy")
+@metricq.cli.command(default_token="source-py-dummy")
 def source(server: str, token: str) -> None:
     src = DummySource(token=token, url=server)
     src.run()

examples/metricq_synchronous_source.py

@@ -33,14 +33,13 @@
 import random
 import time
 
+import metricq
 from metricq import SynchronousSource, Timestamp
-from metricq.cli import metricq_command
-from metricq.logging import get_logger
 
-logger = get_logger()
+logger = metricq.get_logger()
 
 
-@metricq_command(default_token="source-py-dummy")
+@metricq.cli.command(default_token="source-py-dummy")
 def synchronous_source(server: str, token: str) -> None:
     ssource = SynchronousSource(token=token, url=server)
     ssource.declare_metrics(

metricq/__init__.py

@@ -52,6 +52,11 @@
 )
 from .version import __version__
 
+try:
+    from . import cli
+except ImportError:
+    pass
+
 # Please keep sorted alphabetically to avoid merge conflicts
 __all__ = [
     "Agent",
@@ -76,4 +81,5 @@
     "Timestamp",
     "TimeValue",
     "__version__",
+    "cli",
 ]

metricq/cli/__init__.py

@@ -1,9 +1,9 @@
 from .decorator import (
-    metricq_command,
-    metricq_metric_option,
-    metricq_server_option,
-    metricq_syslog_option,
-    metricq_token_option,
+    command,
+    metric_option,
+    server_option,
+    syslog_option,
+    token_option,
 )
 from .params import (
     ChoiceParam,
@@ -21,9 +21,9 @@
     "TemplateStringParam",
     "TimestampParam",
     "MetricParam",
-    "metricq_command",
-    "metricq_metric_option",
-    "metricq_server_option",
-    "metricq_syslog_option",
-    "metricq_token_option",
+    "command",
+    "metric_option",
+    "server_option",
+    "syslog_option",
+    "token_option",
 ]