docs: touch up the docs; finish defining a test

links to `unittest.mock` and `dicom_echo.Counter` now resolve correctly

Signed-off-by: Bryant Finney <[email protected]>

Author: bryant-finney

pyproject.toml

@@ -723,6 +723,7 @@ cmd = """
     typer
     typing
     unittest
+    unittest.mock
     --docformat google
     --footer "$PACKAGE_VERSION"
     --mermaid

src/dicom_echo/__init__.py

@@ -16,16 +16,22 @@
 from __future__ import annotations
 
 import sys
+from typing import Literal
 
 if not sys.argv[0].endswith('pdoc'):
     from dicom_echo.backend import (  # pylint: disable=no-name-in-module
         DEFAULT_CALLED_AE_TITLE,
         DEFAULT_CALLING_AE_TITLE,
     )
     from dicom_echo.backend import send as __send  # pylint: disable=no-name-in-module
-else:
-    DEFAULT_CALLED_AE_TITLE = 'ANY-SCP'  # pyright: ignore[reportConstantRedefinition]
-    DEFAULT_CALLING_AE_TITLE = 'ECHOSCU'  # pyright: ignore[reportConstantRedefinition]
+else:  # pragma: no cover
+    # copy `backend.pyi` contents so the documentation can be built without cargo
+
+    DEFAULT_CALLED_AE_TITLE: Literal['ANY-SCP'] = 'ANY-SCP'  # type: ignore[no-redef]
+    """By default, specify this AE title for the target SCP."""
+
+    DEFAULT_CALLING_AE_TITLE: Literal['ECHOSCU'] = 'ECHOSCU'  # type: ignore[no-redef]
+    """By default, specify this AE title for the SCU sending the `C-ECHO` message."""
 
     def __send(
         address: str,
@@ -41,7 +47,7 @@ def __send(
         return 0
 
 
-__all__ = ['DEFAULT_CALLED_AE_TITLE', 'DEFAULT_CALLING_AE_TITLE', 'send']
+__all__ = ['DEFAULT_CALLED_AE_TITLE', 'DEFAULT_CALLING_AE_TITLE', 'Counter', 'send']
 
 __version__ = '0.0.0'
 __version_tuple__ = (0, 0, 0)
@@ -58,27 +64,22 @@ def increment(self) -> int:
         return self.count
 
 
-class Sentinel:
-    """Explicitly define a class for the sentinel object for type annotations."""
-
-
 counter = Counter()
-sentinel = Sentinel()
 
 
 def send(
     address: str,
     /,
     called_ae_title: str = DEFAULT_CALLED_AE_TITLE,
     calling_ae_title: str = DEFAULT_CALLING_AE_TITLE,
-    message_id: int | Sentinel = sentinel,
+    message_id: int | Counter = counter,
 ) -> int:
     """Send a `C-ECHO` message to the given address.
 
-    If `message_id` is not overwritten, a global counter will be incremented and passed.
+    If `message_id` is not provided, a global counter will be incremented and passed.
 
     Reference: [DICOM Standard Part 7, Section 9.1.5](https://www.dicomstandard.org/standards/view/message-exchange#sect_9.1.5)
     """
-    if isinstance(message_id, Sentinel):
+    if isinstance(message_id, Counter):
         message_id = counter.increment()
     return __send(address, called_ae_title=called_ae_title, calling_ae_title=calling_ae_title, message_id=message_id)

tests/test_pycli.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+import subprocess
+import sys
 from typing import TYPE_CHECKING
 
 import rich.emoji
@@ -54,6 +56,10 @@ def test_version() -> None:
 
 def test_version_called_as_module() -> None:
     """Test the CLI output when the utility is invoked as a Python module."""
+    out = subprocess.check_output([sys.executable, '-m', 'dicom_echo', '--version'], text=True)
+
+    assert 'dicom_echo' in out
+    assert echo.__version__ in out
 
 
 def test_host_aetitle(mock_send_rc0: MagicMock) -> None: