From 0554b2c16434deb3f241392554ff7ebd3eaa3e50 Mon Sep 17 00:00:00 2001 From: "Jason M. Gates" Date: Tue, 14 Jan 2025 07:54:13 -0700 Subject: [PATCH] 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 | 2 +- doc/source/spelling_wordlist.txt | 4 +- doc/source/trace.rst | 16 -------- doc/source/trace_collector.rst | 16 ++++++++ shell_logger/shell_logger.py | 4 +- shell_logger/{trace.py => trace_collector.py} | 41 ++++++++++--------- 6 files changed, 43 insertions(+), 40 deletions(-) delete mode 100644 doc/source/trace.rst create mode 100644 doc/source/trace_collector.rst rename shell_logger/{trace.py => trace_collector.py} (78%) diff --git a/doc/source/index.rst b/doc/source/index.rst index 36acb8c..3bb719d 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -10,7 +10,7 @@ shell-logger shell abstract_method stats_collector - trace + trace_collector html_utilities |Code lines| diff --git a/doc/source/spelling_wordlist.txt b/doc/source/spelling_wordlist.txt index e2c9a8c..e311b19 100644 --- a/doc/source/spelling_wordlist.txt +++ b/doc/source/spelling_wordlist.txt @@ -16,5 +16,5 @@ nan NaN encodable unproxied -STrace -LTrace +STraceCollector +LTraceCollector diff --git a/doc/source/trace.rst b/doc/source/trace.rst deleted file mode 100644 index f48daff..0000000 --- a/doc/source/trace.rst +++ /dev/null @@ -1,16 +0,0 @@ -Trace -===== - -.. autoclass:: shell_logger.trace.Trace - -.. automethod:: shell_logger.trace::trace_collector - -STrace ------- - -.. autoclass:: shell_logger.trace.STrace - -LTrace ------- - -.. autoclass:: shell_logger.trace.LTrace diff --git a/doc/source/trace_collector.rst b/doc/source/trace_collector.rst new file mode 100644 index 0000000..3c73d9c --- /dev/null +++ b/doc/source/trace_collector.rst @@ -0,0 +1,16 @@ +TraceCollector +============== + +.. autoclass:: shell_logger.trace.TraceCollector + +.. automethod:: shell_logger.trace::trace_collector + +STraceCollector +--------------- + +.. autoclass:: shell_logger.trace.STraceCollector + +LTraceCollector +--------------- + +.. autoclass:: shell_logger.trace.LTraceCollector diff --git a/shell_logger/shell_logger.py b/shell_logger/shell_logger.py index a4b6b02..65da646 100644 --- a/shell_logger/shell_logger.py +++ b/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: diff --git a/shell_logger/trace.py b/shell_logger/trace_collector.py similarity index 78% rename from shell_logger/trace.py rename to shell_logger/trace_collector.py index 7d6938d..3681326 100644 --- a/shell_logger/trace.py +++ b/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")