DM-39781: Clean docs and add ruff configuration

.github/workflows/lint.yaml

@@ -9,3 +9,8 @@ on:
 jobs:
   call-workflow:
     uses: lsst/rubin_workflows/.github/workflows/lint.yaml@main
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: chartboost/ruff-action@v1

.pre-commit-config.yaml

@@ -21,7 +21,8 @@ repos:
     hooks:
       - id: isort
         name: isort (python)
-  - repo: https://github.com/PyCQA/flake8
-    rev: 6.0.0
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.0.275
     hooks:
-      - id: flake8
+      - id: ruff

pyproject.toml

@@ -139,8 +139,8 @@ convention = "numpy"
 # We allow methods to inherit docstrings and this is not compatible with D102.
 # Docstring at the very first line is not required
 # D200, D205 and D400 all complain if the first sentence of the docstring does
-# not fit on one line.
-add-ignore = ["D107", "D105", "D102", "D100", "D200", "D205", "D400"]
+# not fit on one line. We do not require docstrings in __init__ files (D104).
+add-ignore = ["D107", "D105", "D102", "D100", "D200", "D205", "D400", "D104"]
 
 [tool.coverage.report]
 show_missing = true
@@ -151,3 +151,50 @@ exclude_lines = [
     "if __name__ == .__main__.:",
     "if TYPE_CHECKING:",
 ]
+
+[tool.ruff]
+exclude = [
+    "__init__.py",
+    "lex.py",
+    "yacc.py",
+]
+ignore = [
+    "N802",
+    "N803",
+    "N806",
+    "N812",
+    "N815",
+    "N816",
+    "N999",
+    "D107",
+    "D105",
+    "D102",
+    "D104",
+    "D100",
+    "D200",
+    "D205",
+    "D400",
+    "E402", # Module level import not at top of file (against Rubin style)
+]
+line-length = 110
+select = [
+    "E",  # pycodestyle
+    "F",  # pycodestyle
+    "N",  # pep8-naming
+    "W",  # pycodestyle
+    "D",  # pydocstyle
+]
+target-version = "py310"
+extend-select = [
+    "RUF100", # Warn about unused noqa
+]
+
+[tool.ruff.per-file-ignores]
+# parserYacc docstrings can not be fixed. Docstrings are used to define grammar.
+"python/lsst/daf/butler/registry/queries/expressions/parser/parserYacc.py" = ["D401", "D403"]
+
+[tool.ruff.pycodestyle]
+max-doc-length = 79
+
+[tool.ruff.pydocstyle]
+convention = "numpy"

python/lsst/daf/butler/_butler.py

@@ -19,8 +19,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""
-Butler top level classes.
+"""Butler top level classes.
 """
 from __future__ import annotations
 
@@ -1410,7 +1409,7 @@ def getURIs(
         run: str | None = None,
         **kwargs: Any,
     ) -> DatasetRefURIs:
-        """Returns the URIs associated with the dataset.
+        """Return the URIs associated with the dataset.
 
         Parameters
         ----------

python/lsst/daf/butler/_butlerConfig.py

@@ -19,8 +19,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""
-Configuration classes specific to the Butler
+"""Configuration classes specific to the Butler.
 """
 from __future__ import annotations
 
@@ -41,7 +40,7 @@
 
 
 class ButlerConfig(Config):
-    """Contains the configuration for a `Butler`
+    """Contains the configuration for a `Butler`.
 
     The configuration is read and merged with default configurations for
     the particular classes. The defaults are read according to the rules

python/lsst/daf/butler/_deferredDatasetHandle.py

@@ -19,8 +19,7 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-"""
-Module containing classes used with deferring dataset loading
+"""Module containing classes used with deferring dataset loading.
 """
 from __future__ import annotations
 
@@ -45,7 +44,7 @@ def get(
         parameters: dict | None = None,
         storageClass: str | StorageClass | None = None,
     ) -> Any:
-        """Retrieves the dataset pointed to by this handle
+        """Retrieve the dataset pointed to by this handle.
 
         This handle may be used multiple times, possibly with different
         parameters.

python/lsst/daf/butler/_quantum_backed.py

@@ -304,7 +304,9 @@ def _initialize(
         search_paths: list[str] | None = None,
         dataset_types: Mapping[str, DatasetType] | None = None,
     ) -> QuantumBackedButler:
-        """Internal method with common implementation used by `initialize` and
+        """Initialize quantum-backed butler.
+
+        Internal method with common implementation used by `initialize` and
         `for_output`.
 
         Parameters

python/lsst/daf/butler/cli/butler.py

@@ -82,16 +82,19 @@ def _importPlugin(pluginName: str) -> types.ModuleType | type | None | click.Com
 
 class LoaderCLI(click.MultiCommand, abc.ABC):
     """Extends `click.MultiCommand`, which dispatches to subcommands, to load
-    subcommands at runtime."""
+    subcommands at runtime.
+    """
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
 
     @property
     @abc.abstractmethod
     def localCmdPkg(self) -> str:
-        """localCmdPkg identifies the location of the commands that are in this
-        package. `getLocalCommands` assumes that the commands can be found in
+        """Identifies the location of the commands that are in this
+        package.
+
+        `getLocalCommands` assumes that the commands can be found in
         `localCmdPkg.__all__`, if this is not the case then getLocalCommands
         should be overridden.
 
@@ -123,9 +126,11 @@ def getLocalCommands(self) -> defaultdict[str, list[str]]:
         )
 
     def list_commands(self, ctx: click.Context) -> list[str]:
-        """Used by Click to get all the commands that can be called by the
+        """Get all the commands that can be called by the
         butler command, it is used to generate the --help output.
 
+        Used by Click.
+
         Parameters
         ----------
         ctx : `click.Context`
@@ -142,7 +147,9 @@ def list_commands(self, ctx: click.Context) -> list[str]:
         return sorted(commands)
 
     def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
-        """Used by Click to get a single command for execution.
+        """Get a single command for execution.
+
+        Used by Click.
 
         Parameters
         ----------
@@ -177,7 +184,8 @@ def get_command(self, ctx: click.Context, name: str) -> click.Command | None:
     def _setupLogging(self, ctx: click.Context | None) -> None:
         """Init the logging system and config it for the command.
 
-        Subcommands may further configure the log settings."""
+        Subcommands may further configure the log settings.
+        """
         if isinstance(ctx, click.Context):
             CliLog.initLog(
                 longlog=ctx.params.get(long_log_option.name(), False),
@@ -228,7 +236,8 @@ def _cmdNameToFuncName(cls, commandName: str) -> str:
         """Convert butler command name to function name: change dashes (used in
         commands) to underscores (used in functions), and for local-package
         commands names that conflict with python keywords, change the local,
-        legal, function name to the command name."""
+        legal, function name to the command name.
+        """
         return commandName.replace("-", "_")
 
     @staticmethod
@@ -308,7 +317,6 @@ def _raiseIfDuplicateCommands(commands: defaultdict[str, list[str]]) -> None:
             Raised if a command is offered by more than one package, with an
             error message to be displayed to the user.
         """
-
         msg = ""
         for command, packages in commands.items():
             if len(packages) > 1:
@@ -318,6 +326,8 @@ def _raiseIfDuplicateCommands(commands: defaultdict[str, list[str]]) -> None:
 
 
 class ButlerCLI(LoaderCLI):
+    """Specialized command loader implementing the ``butler`` command."""
+
     localCmdPkg = "lsst.daf.butler.cli.cmd"
 
     pluginEnvVar = "DAF_BUTLER_PLUGINS"
@@ -356,11 +366,15 @@ def _cmdNameToFuncName(cls, commandName: str) -> str:
 @log_label_option()
 @ClickProgressHandler.option
 def cli(log_level: str, long_log: bool, log_file: str, log_tty: bool, log_label: str, progress: bool) -> None:
-    # log_level is handled by get_command and list_commands, and is called in
-    # one of those functions before this is called. long_log is handled by
-    # setup_logging.
+    """Command line interface for butler.
+
+    log_level is handled by get_command and list_commands, and is called in
+    one of those functions before this is called. long_log is handled by
+    setup_logging.
+    """
     pass
 
 
 def main() -> click.Command:
+    """Return main entry point for command-line."""
     return cli()

python/lsst/daf/butler/cli/cliLog.py

@@ -69,7 +69,8 @@ class CliLog:
 
     This class can perform log uninitialization, which allows command line
     interface code that initializes logging to run unit tests that execute in
-    batches, without affecting other unit tests. See ``resetLog``."""
+    batches, without affecting other unit tests. See ``resetLog``.
+    """
 
     defaultLsstLogLevel = lsstLog.FATAL if lsstLog is not None else None
 
@@ -394,7 +395,8 @@ def __repr__(self) -> str:
     @classmethod
     def _recordComponentSetting(cls, component: str | None) -> None:
         """Cache current levels for the given component in the list of
-        component levels."""
+        component levels.
+        """
         componentSettings = cls.ComponentSettings(component)
         cls._componentSettings.append(componentSettings)
 

python/lsst/daf/butler/cli/cmd/commands.py

@@ -112,7 +112,6 @@ def associate(**kwargs: Any) -> None:
 @options_file_option()
 def butler_import(*args: Any, **kwargs: Any) -> None:
     """Import data into a butler repository."""
-
     # `reuse_ids`` is not used by `butlerImport`.
     reuse_ids = kwargs.pop("reuse_ids", False)
     if reuse_ids:

python/lsst/daf/butler/cli/opt/optionGroups.py

@@ -31,6 +31,8 @@
 
 
 class query_datasets_options(OptionGroup):  # noqa: N801
+    """A collection of options common to querying datasets."""
+
     def __init__(self, repo: bool = True, showUri: bool = True, useArguments: bool = True) -> None:
         self.decorators = []
         if repo:

python/lsst/daf/butler/cli/opt/options.py

@@ -60,6 +60,8 @@
 
 
 class CollectionTypeCallback:
+    """Helper class for handling different collection types."""
+
     collectionTypes = tuple(collectionType.name for collectionType in CollectionType.all())
 
     @staticmethod

python/lsst/daf/butler/cli/progress.py

@@ -50,7 +50,7 @@ def __init__(self, **kwargs: Any):
 
     @classmethod
     def callback(cls, ctx: click.Context, params: click.Parameter, value: Any) -> None:
-        """A `click` callback that installs this handler as the global handler
+        """`click` callback that installs this handler as the global handler
         for progress bars.
 
         Should usually be called only by the `option` method.
@@ -62,7 +62,7 @@ def callback(cls, ctx: click.Context, params: click.Parameter, value: Any) -> No
 
     @classmethod
     def option(cls, cmd: Any) -> Any:
-        """A `click` command decorator that adds a ``--progress`` option
+        """`click` command decorator that adds a ``--progress`` option
         that installs a default-constructed instance of this progress handler.
         """
         return click.option(