refactor!: Rename trace module

Ruff A005 detected that the `trace` module was shadowing a built-in.  We
should've noticed this years ago.  This commit renames it and the
classes therein so there's no confusion between what's provided by
`shell-logger` vs the standard library.  It also improves the parity
between this module and `stats_collectors`, which improves readability
and eases maintainability.

Note that this is a (rather unfortunate) breaking change.

doc/source/index.rst

@@ -10,7 +10,7 @@ shell-logger
    shell
    abstract_method
    stats_collector
-   trace
+   trace_collector
    html_utilities
 
 |Code lines|

doc/source/spelling_wordlist.txt

@@ -16,5 +16,5 @@ nan
 NaN
 encodable
 unproxied
-STrace
-LTrace
+STraceCollector
+LTraceCollector

doc/source/trace_collector.rst

@@ -0,0 +1,16 @@
+TraceCollector
+==============
+
+.. autoclass:: shell_logger.trace_collector.TraceCollector
+
+.. automethod:: shell_logger.trace_collector::trace_collector
+
+STraceCollector
+---------------
+
+.. autoclass:: shell_logger.trace_collector.STraceCollector
+
+LTraceCollector
+---------------
+
+.. autoclass:: shell_logger.trace_collector.LTraceCollector

shell_logger/shell_logger.py

@@ -34,7 +34,7 @@
 )
 from .shell import Shell
 from .stats_collector import stats_collectors
-from .trace import trace_collector
+from .trace_collector import trace_collector
 
 
 class ShellLogger:
@@ -606,7 +606,7 @@ def _run(self, command: str, **kwargs) -> SimpleNamespace:
         Parameters:
             command:  The command to execute.
             **kwargs:  Additional arguments to be passed on to the
-                :class:`StatsCollector` s, :class:`Trace` s,
+                :class:`StatsCollector` s, :class:`TraceCollector` s,
                 :func:`shell.run`, etc.
 
         Returns:

shell_logger/trace.py → shell_logger/trace_collector.py

@@ -14,22 +14,25 @@
 from .abstract_method import AbstractMethod
 
 
-def trace_collector(**kwargs) -> Trace:
+def trace_collector(**kwargs) -> TraceCollector:
     """
     Generate trace collectors.
 
-    A factory method that returns any subclass of :class:`Trace` that
-    has the ``@Trace.subclass`` decorator applied to it.
+    A factory method that returns any subclass of
+    :class:`TraceCollector` that has the ``@TraceCollector.subclass``
+    decorator applied to it.
 
     Parameters:
-        **kwargs:  Any supported arguments of the :class:`Trace`
-            subclass.
+        **kwargs:  Any supported arguments of the
+            :class:`TraceCollector` subclass.
 
     Returns:
-        A single instance of a :class:`Trace` subclass.
+        A single instance of a :class:`TraceCollector` subclass.
     """
     trace_name = kwargs["trace"]
-    collectors = [c for c in Trace.subclasses if c.trace_name == trace_name]
+    collectors = [
+        c for c in TraceCollector.subclasses if c.trace_name == trace_name
+    ]
     if len(collectors) == 1:
         collector = collectors[0]
         return collector(**kwargs)
@@ -40,7 +43,7 @@ def trace_collector(**kwargs) -> Trace:
     raise RuntimeError(message)
 
 
-class Trace:
+class TraceCollector:
     """
     Trace a command run in the underlying shell.
 
@@ -57,16 +60,16 @@ def subclass(trace_subclass: type):
         Mark a class as being a supported trace collector.
 
         This is a class decorator that adds to a list of supported
-        :class:`Trace` classes for the :func:`trace_collector` factory
-        method.
+        :class:`TraceCollector` classes for the :func:`trace_collector`
+        factory method.
         """
-        if issubclass(trace_subclass, Trace):
-            Trace.subclasses.append(trace_subclass)
+        if issubclass(trace_subclass, TraceCollector):
+            TraceCollector.subclasses.append(trace_subclass)
         return trace_subclass
 
     def __init__(self, **kwargs):
         """
-        Initialize the :class:`Trace` object.
+        Initialize the :class:`TraceCollector` object.
 
         Set up the output file where the trace information will be
         written.
@@ -104,8 +107,8 @@ def command(self, command: str):
         return f"{self.trace_args} -- {command}"
 
 
-@Trace.subclass
-class STrace(Trace):
+@TraceCollector.subclass
+class STraceCollector(TraceCollector):
     """
     Run ``strace`` on commands.
 
@@ -116,7 +119,7 @@ class STrace(Trace):
     trace_name = "strace"
 
     def __init__(self, **kwargs) -> None:
-        """Initialize the :class:`STrace` instance."""
+        """Initialize the :class:`STraceCollector` instance."""
         super().__init__(**kwargs)
         self.summary = bool(kwargs.get("summary"))
         self.expression = kwargs.get("expression")
@@ -132,8 +135,8 @@ def trace_args(self) -> str:
         return args
 
 
-@Trace.subclass
-class LTrace(Trace):
+@TraceCollector.subclass
+class LTraceCollector(TraceCollector):
     """
     Run ``ltrace`` on commands.
 
@@ -144,7 +147,7 @@ class LTrace(Trace):
     trace_name = "ltrace"
 
     def __init__(self, **kwargs):
-        """Initialize the :class:`LTrace` instance."""
+        """Initialize the :class:`LTraceCollector` instance."""
         super().__init__(**kwargs)
         self.summary = bool(kwargs.get("summary"))
         self.expression = kwargs.get("expression")