enforce numpydoc with ruff (#4214)

* style(ruff): lint docstrings

* style(ruff): run safe auto-fixes

* style(ruff): apply unsafe fixes

* fix remaining ruff errors manually

* manually convert some docstrings

* convert more to numpydoc

* fix: grammar

Co-authored-by: Copilot <[email protected]>

* replaceall remaining docstrings

* remove redundant types

* fix some tests

* revert: convert back to RuntimeError

* fix: use existing path everywhere

* various fixes

* fix test

* update schema

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Matthew R. Becker <[email protected]>

Author: 3 people

conda_forge_tick/auto_tick.py

@@ -156,11 +156,21 @@ def _prepare_feedstock_repository(
 
     Any errors are written to the pr_info attribute of the feedstock context and logged.
 
-    :param backend: The GitPlatformBackend instance to use.
-    :param context: The current context
-    :param branch: The branch to create in the forked repository.
-    :param base_branch: The base branch to branch from.
-    :return: True if the repository was successfully prepared, False otherwise.
+    Parameters
+    ----------
+    backend
+        The GitPlatformBackend instance to use.
+    context
+        The current context
+    branch
+        The branch to create in the forked repository.
+    base_branch
+        The base branch to branch from.
+
+    Returns
+    -------
+    bool
+        True if the repository was successfully prepared, False otherwise.
     """
     try:
         backend.fork(context.git_repo_owner, context.git_repo_name)
@@ -201,12 +211,24 @@ def _commit_migration(
     """
     Commit a migration that has been run in the local clone of a feedstock repository.
     If an error occurs during the commit, it is logged.
-    :param cli: The GitCli instance to use.
-    :param context: The FeedstockContext instance.
-    :param commit_message: The commit message to use.
-    :param allow_empty_commits: Whether the migrator allows empty commits.
-    :param raise_commit_errors: Whether to raise an exception if an error occurs during the commit.
-    :raises GitCliError: If an error occurs during the commit and raise_commit_errors is True.
+
+    Parameters
+    ----------
+    cli
+        The GitCli instance to use.
+    context
+        The FeedstockContext instance.
+    commit_message
+        The commit message to use.
+    allow_empty_commits
+        Whether the migrator allows empty commits.
+    raise_commit_errors
+        Whether to raise an exception if an error occurs during the commit.
+
+    Raises
+    ------
+    GitCliError
+        If an error occurs during the commit and raise_commit_errors is True.
     """
     cli.add(
         context.local_clone_dir,
@@ -226,9 +248,7 @@ def _commit_migration(
 
 @dataclass(frozen=True)
 class _RerenderInfo:
-    """
-    Additional information about a rerender operation.
-    """
+    """Additional information about a rerender operation."""
 
     nontrivial_changes: bool
     """
@@ -292,10 +312,17 @@ def _should_automerge(migrator: Migrator, context: FeedstockContext) -> bool:
     """
     Determine if a migration should be auto merged based on the feedstock and migrator settings.
 
-    :param migrator: The migrator to check.
-    :param context: The feedstock context.
+    Parameters
+    ----------
+    migrator
+        The migrator to check.
+    context
+        The feedstock context.
 
-    :return: True if the migrator should be auto merged, False otherwise.
+    Returns
+    -------
+    bool
+        True if the migrator should be auto merged, False otherwise.
     """
     if isinstance(migrator, Version):
         return context.automerge in [True, "version"]
@@ -396,12 +423,20 @@ def _check_and_process_solvability(
     by setting the corresponding fields in the feedstock attributes.
     If the recipe is solvable, reset the fields that track the solvability check status.
 
-    :param migrator: The migrator that was run
-    :param context: The current FeedstockContext of the feedstock that was migrated
-    :param base_branch: The branch of the feedstock repository that is the migration target
+    Parameters
+    ----------
+    migrator
+        The migrator that was run
+    context
+        The current FeedstockContext of the feedstock that was migrated
+    base_branch
+        The branch of the feedstock repository that is the migration target
 
-    :returns: True if the migration can proceed normally, False if a required solvability check failed and the migration
-    needs to be aborted
+    Returns
+    -------
+    bool
+        True if the migration can proceed normally, False if a required solvability check failed and the migration
+        needs to be aborted
     """
     if not _is_solvability_check_needed(migrator, context, base_branch):
         return True
@@ -486,7 +521,7 @@ def run(
     base_branch: str = "main",
     **kwargs: typing.Any,
 ) -> tuple[MigrationUidTypedDict, dict] | tuple[Literal[False], Literal[False]]:
-    """For a given feedstock and migration run the migration
+    """For a given feedstock and migration run the migration.
 
     Parameters
     ----------
@@ -510,7 +545,6 @@ def run(
     pr_json: dict
         The PR json object for recreating the PR as needed
     """
-
     # sometimes we get weird directory issues so make sure we reset
     os.chdir(BOT_HOME_DIR)
 
@@ -1131,8 +1165,7 @@ def _setup_limits():
 
 
 def _update_nodes_with_bot_rerun(gx: nx.DiGraph):
-    """Go through all the open PRs and check if they are rerun"""
-
+    """Go through all the open PRs and check if they are rerun."""
     print("processing bot-rerun labels", flush=True)
 
     for i, (name, node) in enumerate(gx.nodes.items()):
@@ -1194,8 +1227,7 @@ def _filter_ignored_versions(attrs, version):
 
 
 def _update_nodes_with_new_versions(gx):
-    """Updates every node with it's new version (when available)"""
-
+    """Update every node with it's new version (when available)."""
     print("updating nodes with new versions", flush=True)
 
     version_nodes = get_all_keys_for_hashmap("versions")

conda_forge_tick/cf_tick_schema.json

@@ -24,7 +24,7 @@
     },
     "BotConfigVersionUpdates": {
       "additionalProperties": false,
-      "description": "This dictates the behavior of the conda-forge auto-tick bot for version\nupdates",
+      "description": "Dictates the behavior of the conda-forge auto-tick bot for version\nupdates.",
       "properties": {
         "random_fraction_to_keep": {
           "anyOf": [
@@ -106,7 +106,7 @@
     }
   },
   "additionalProperties": false,
-  "description": "This dictates the behavior of the conda-forge auto-tick bot which issues\nautomatic version updates/migrations for feedstocks.\nA valid example is:\n\n```yaml\nbot:\n    # can the bot automerge PRs it makes on this feedstock\n    automerge: true\n    # only automerge on successful version PRs, migrations are not automerged\n    automerge: 'version'\n    # only automerge on successful migration PRs, versions are not automerged\n    automerge: 'migration'\n\n    # only open PRs if resulting environment is solvable, useful for tightly coupled packages\n    check_solvable: true\n\n    # The bot.inspection key in the conda-forge.yml can have one of seven possible values and controls\n    # the bots behaviour for automatic dependency updates:\n    inspection: hint  # generate hints using source code (backwards compatible)\n    inspection: hint-all  # generate hints using all methods\n    inspection: hint-source  # generate hints using only source code\n    inspection: hint-grayskull  # generate hints using only grayskull\n    inspection: update-all  # update recipe using all methods\n    inspection: update-source  # update recipe using only source code\n    inspection: update-grayskull  # update recipe using only grayskull\n    inspection: disabled # don't update recipe, don't generate hints\n\n    # any branches listed in this section will get bot migration PRs in addition\n    # to the default branch\n    abi_migration_branches:\n        - 'v1.10.x'\n\n    version_updates:\n        # use this for packages that are updated too frequently\n        random_fraction_to_keep: 0.1  # keeps 10% of versions at random\n        exclude:\n            - '08.14'\n```\n\nThe `abi_migration_branches` feature is useful to, for example, add a\nlong-term support (LTS) branch for a package.",
+  "description": "Dictates the behavior of the conda-forge auto-tick bot which issues\nautomatic version updates/migrations for feedstocks.\n\nA valid example is:\n\n```yaml\nbot:\n    # can the bot automerge PRs it makes on this feedstock\n    automerge: true\n    # only automerge on successful version PRs, migrations are not automerged\n    automerge: 'version'\n    # only automerge on successful migration PRs, versions are not automerged\n    automerge: 'migration'\n\n    # only open PRs if resulting environment is solvable, useful for tightly coupled packages\n    check_solvable: true\n\n    # The bot.inspection key in the conda-forge.yml can have one of seven possible values and controls\n    # the bots behaviour for automatic dependency updates:\n    inspection: hint  # generate hints using source code (backwards compatible)\n    inspection: hint-all  # generate hints using all methods\n    inspection: hint-source  # generate hints using only source code\n    inspection: hint-grayskull  # generate hints using only grayskull\n    inspection: update-all  # update recipe using all methods\n    inspection: update-source  # update recipe using only source code\n    inspection: update-grayskull  # update recipe using only grayskull\n    inspection: disabled # don't update recipe, don't generate hints\n\n    # any branches listed in this section will get bot migration PRs in addition\n    # to the default branch\n    abi_migration_branches:\n        - 'v1.10.x'\n\n    version_updates:\n        # use this for packages that are updated too frequently\n        random_fraction_to_keep: 0.1  # keeps 10% of versions at random\n        exclude:\n            - '08.14'\n```\n\nThe `abi_migration_branches` feature is useful to, for example, add a\nlong-term support (LTS) branch for a package.",
   "properties": {
     "automerge": {
       "anyOf": [

conda_forge_tick/chaindb.py

@@ -1,6 +1,7 @@
 """
-The code in this module is from xonsh (https://github.com/xonsh/xonsh/blob/main/xonsh/lib/collections.py)
-under the folloiwing license:
+The code in this module is from xonsh (https://github.com/xonsh/xonsh/blob/main/xonsh/lib/collections.py).
+
+License:
 
 Copyright 2015-2016, the xonsh developers. All rights reserved.
 
@@ -51,7 +52,8 @@ def __new__(cls):
 
 class ChainDB(ChainMap):
     """A ChainMap who's ``_getitem__`` returns either a ChainDB or
-    the result. The results resolve to the outermost mapping."""
+    the result. The results resolve to the outermost mapping.
+    """
 
     def __getitem__(self, key):
         res = None

conda_forge_tick/cli.py

@@ -238,9 +238,7 @@ def make_import_to_package_mapping(
     ctx: CliContext,
     max_artifacts: int,
 ) -> None:
-    """
-    Make the import to package mapping.
-    """
+    """Make the import to package mapping."""
     from . import import_to_pkg
 
     import_to_pkg.main(ctx, max_artifacts)
@@ -251,9 +249,7 @@ def make_import_to_package_mapping(
 def make_migrators(
     ctx: CliContext,
 ) -> None:
-    """
-    Make the migrators.
-    """
+    """Make the migrators."""
     from . import make_migrators as _make_migrators
 
     _make_migrators.main(ctx)
@@ -281,9 +277,7 @@ def react_to_event(
     event: str,
     uid: str,
 ) -> None:
-    """
-    React to an event.
-    """
+    """React to an event."""
     from .events import react_to_event
 
     react_to_event(ctx, event, uid)
@@ -292,9 +286,7 @@ def react_to_event(
 @main.command(name="clean-disk-space")
 @click.option("--ci-service", required=True, type=click.Choice(["github-actions"]))
 def clean_disk_space(ci_service) -> None:
-    """
-    Clean up disk space on CI services.
-    """
+    """Clean up disk space on CI services."""
     from .os_utils import clean_disk_space
 
     clean_disk_space(ci_service)

conda_forge_tick/config_schema.py

@@ -47,8 +47,8 @@ class BotConfigVersionUpdatesSourcesChoice(StrEnum):
 
 class BotConfigVersionUpdates(BaseModel):
     """
-    This dictates the behavior of the conda-forge auto-tick bot for version
-    updates
+    Dictates the behavior of the conda-forge auto-tick bot for version
+    updates.
     """
 
     model_config: ConfigDict = ConfigDict(extra="forbid")
@@ -104,8 +104,9 @@ class BotConfigVersionUpdates(BaseModel):
 
 class BotConfig(BaseModel):
     """
-    This dictates the behavior of the conda-forge auto-tick bot which issues
+    Dictates the behavior of the conda-forge auto-tick bot which issues
     automatic version updates/migrations for feedstocks.
+
     A valid example is:
 
     ```yaml

conda_forge_tick/container_cli.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-"""This file runs specific tasks for the bot.
+"""Run specific tasks for the bot.
 
 All imports from the bot need to be guarded by putting them in the subcommands.
 This ensures that we can set important environment variables before any imports,
@@ -45,7 +45,7 @@
 
 @contextmanager
 def _setenv(name, value):
-    """set an environment variable temporarily"""
+    """Set an environment variable temporarily."""
     old = os.environ.get(name)
     try:
         os.environ[name] = value

conda_forge_tick/contexts.py

@@ -22,7 +22,7 @@
 
 @dataclass
 class MigratorSessionContext:
-    """Singleton session context. There should generally only be one of these"""
+    """Singleton session context. There should generally only be one of these."""
 
     graph: DiGraph = None
     smithy_version: str = ""
@@ -56,9 +56,7 @@ def git_repo_name(self) -> str:
 
     @property
     def git_http_ref(self) -> str:
-        """
-        A link to the feedstock's GitHub repository.
-        """
+        """A link to the feedstock's GitHub repository."""
         return f"https://github.com/{self.git_repo_owner}/{self.git_repo_name}"
 
     @property

conda_forge_tick/depfinder_api.py

@@ -123,7 +123,7 @@ def simple_import_to_pkg_map(
     ignore=None,
     custom_namespaces=None,
 ):
-    """Provide the map between all the imports and their possible packages
+    """Provide the map between all the imports and their possible packages.
 
     Parameters
     ----------

conda_forge_tick/deploy.py

@@ -186,7 +186,7 @@ def _get_files_to_delete():
 
 
 def _get_pth_commit_message(pth):
-    """make a nice message for stuff managed via LazyJson."""
+    """Make a nice message for stuff managed via LazyJson."""
     step_name = os.environ.get("GITHUB_WORKFLOW", "update graph")
     msg_pth = pth
     parts = pth.split("/")
@@ -204,7 +204,7 @@ def _reset_and_restore_file(pth):
 
 
 def deploy(ctx: CliContext, dirs_to_deploy: list[str] = None):
-    """Deploy the graph to GitHub"""
+    """Deploy the graph to GitHub."""
     if ctx.dry_run:
         print("(dry run) deploying")
         return

conda_forge_tick/env_management.py

@@ -14,7 +14,7 @@ def __init__(self):
         self.classified_info = {}
 
     def hide_env_vars(self):
-        """Remove sensitive env vars"""
+        """Remove sensitive env vars."""
         self.classified_info.update(
             {
                 k: os.environ.pop(k, self.classified_info.get(k, None))
@@ -23,15 +23,16 @@ def hide_env_vars(self):
         )
 
     def reveal_env_vars(self):
-        """Restore sensitive env vars"""
+        """Restore sensitive env vars."""
         os.environ.update(
             **{k: v for k, v in self.classified_info.items() if v is not None}
         )
 
     @contextmanager
     def sensitive_env(self):
         """Add sensitive keys to environ if needed, when ctx is finished remove keys and update the sensitive env
-        in case any were updated inside the ctx"""
+        in case any were updated inside the ctx.
+        """
         self.reveal_env_vars()
         yield os.environ
         self.hide_env_vars()