Add flake8-docstrings to pre-commit (conda#12620)

.pre-commit-config.yaml

@@ -69,3 +69,5 @@ repos:
     hooks:
       # lint Python codes
       - id: flake8
+        args: [--docstring-convention=pep257]
+        additional_dependencies: [flake8-docstrings]

conda/activate.py

@@ -1268,10 +1268,12 @@ def _yield_commands(self, cmds_dict):
 
 
 def _build_activator_cls(shell):
-    """Construct the activator class dynamically from a base activator and any
-    number of formatters, appended using '+' to the name. For example,
-    `posix+json` (as in `conda shell.posix+json activate`) would use the
-    `PosixActivator` base class and add the `JSONFormatMixin`."""
+    """Dynamically construct the activator class.
+
+    Detect the base activator and any number of formatters (appended using '+' to the base name).
+    For example, `posix+json` (as in `conda shell.posix+json activate`) would use the
+    `PosixActivator` base class and add the `JSONFormatMixin`.
+    """
     shell_etc = shell.split("+")
     activator, formatters = shell_etc[0], shell_etc[1:]
     bases = [activator_map[activator]]

conda/api.py

@@ -43,9 +43,9 @@ def __init__(
                 A prioritized list of channels to use for the solution.
             subdirs (Sequence[str]):
                 A prioritized list of subdirs to use for the solution.
-            specs_to_add (Set[:class:`MatchSpec`]):
+            specs_to_add (set[:class:`MatchSpec`]):
                 The set of package specs to add to the prefix.
-            specs_to_remove (Set[:class:`MatchSpec`]):
+            specs_to_remove (set[:class:`MatchSpec`]):
                 The set of package specs to remove from the prefix.
 
         """
@@ -89,7 +89,7 @@ def solve_final_state(
                 Forces removal of a package without removing packages that depend on it.
 
         Returns:
-            Tuple[PackageRef]:
+            tuple[PackageRef]:
                 In sorted dependency order from roots to leaves, the package references for
                 the solved state of the environment.
 
@@ -129,7 +129,7 @@ def solve_for_diff(
                 depending on the spec exactness.
 
         Returns:
-            Tuple[PackageRef], Tuple[PackageRef]:
+            tuple[PackageRef], tuple[PackageRef]:
                 A two-tuple of PackageRef sequences.  The first is the group of packages to
                 remove from the environment, in sorted dependency order from leaves to roots.
                 The second is the group of packages to add to the environment, in sorted
@@ -221,7 +221,7 @@ def query(self, package_ref_or_match_spec):
                 query object.  A :obj:`str` will be turned into a :obj:`MatchSpec` automatically.
 
         Returns:
-            Tuple[PackageRecord]
+            tuple[PackageRecord]
 
         """
         return tuple(self._internal.query(package_ref_or_match_spec))
@@ -244,7 +244,7 @@ def query_all(package_ref_or_match_spec, channels=None, subdirs=None):
                 If None, will fall back to context.subdirs.
 
         Returns:
-            Tuple[PackageRecord]
+            tuple[PackageRecord]
 
         """
         return tuple(
@@ -323,7 +323,7 @@ def query(self, package_ref_or_match_spec):
                 query object.  A :obj:`str` will be turned into a :obj:`MatchSpec` automatically.
 
         Returns:
-            Tuple[PackageCacheRecord]
+            tuple[PackageCacheRecord]
 
         """
         return tuple(self._internal.query(package_ref_or_match_spec))
@@ -343,7 +343,7 @@ def query_all(package_ref_or_match_spec, pkgs_dirs=None):
                 If None, will fall back to context.pkgs_dirs.
 
         Returns:
-            Tuple[PackageCacheRecord]
+            tuple[PackageCacheRecord]
 
         """
         return tuple(_PackageCacheData.query_all(package_ref_or_match_spec, pkgs_dirs))
@@ -451,7 +451,7 @@ def query(self, package_ref_or_match_spec):
                 query object.  A :obj:`str` will be turned into a :obj:`MatchSpec` automatically.
 
         Returns:
-            Tuple[PrefixRecord]
+            tuple[PrefixRecord]
 
         """
         return tuple(self._internal.query(package_ref_or_match_spec))

conda/auxlib/type_coercion.py

@@ -188,7 +188,7 @@ def typify(value, type_hint=None):
 
     Args:
         value (Any): Usually a string, not a sequence
-        type_hint (type or Tuple[type]):
+        type_hint (type or tuple[type]):
 
     Examples:
         >>> typify('32')

conda/base/context.py

@@ -1,5 +1,7 @@
 # Copyright (C) 2012 Anaconda, Inc
 # SPDX-License-Identifier: BSD-3-Clause
+from __future__ import annotations
+
 import os
 import platform
 import struct
@@ -11,7 +13,6 @@
 from logging import getLogger
 from os.path import abspath, expanduser, isdir, isfile, join
 from os.path import split as path_split
-from typing import Optional
 
 try:
     from boltons.setutils import IndexedSet
@@ -576,19 +577,19 @@ def platform(self):
         return _platform_map.get(sys.platform, "unknown")
 
     @property
-    def default_threads(self) -> Optional[int]:
+    def default_threads(self) -> int | None:
         return self._default_threads or None
 
     @property
-    def repodata_threads(self) -> Optional[int]:
+    def repodata_threads(self) -> int | None:
         return self._repodata_threads or self.default_threads
 
     @property
-    def fetch_threads(self) -> Optional[int]:
+    def fetch_threads(self) -> int | None:
         return self._fetch_threads or self.default_threads
 
     @property
-    def verify_threads(self) -> Optional[int]:
+    def verify_threads(self) -> int | None:
         if self._verify_threads:
             threads = self._verify_threads
         elif self.default_threads:
@@ -750,15 +751,13 @@ def conda_exe(self):
 
     @property
     def av_data_dir(self):
-        """Directory where critical data for artifact verification (e.g.,
-        various public keys) can be found."""
+        """Where critical artifact verification data (e.g., various public keys) can be found."""
         # TODO (AV): Find ways to make this user configurable?
         return join(self.conda_prefix, "etc", "conda")
 
     @property
     def signing_metadata_url_base(self):
-        """Base URL where artifact verification signing metadata (*.root.json,
-        key_mgr.json) can be obtained."""
+        """Base URL for artifact verification signing metadata (*.root.json, key_mgr.json)."""
         if self._signing_metadata_url_base:
             return self._signing_metadata_url_base
         else:
@@ -770,7 +769,6 @@ def conda_exe_vars_dict(self):
         The vars can refer to each other if necessary since the dict is ordered.
         None means unset it.
         """
-
         if context.dev:
             return {
                 "CONDA_EXE": sys.executable,
@@ -894,13 +892,7 @@ def channels(self):
             if not self.override_channels_enabled:
                 from ..exceptions import OperationNotAllowed
 
-                raise OperationNotAllowed(
-                    dals(
-                        """
-                Overriding channels has been disabled.
-                """
-                    )
-                )
+                raise OperationNotAllowed("Overriding channels has been disabled.")
             elif not (
                 self._argparse_args
                 and "channel" in self._argparse_args
@@ -1082,10 +1074,8 @@ def cpu_flags(self):
         addendum="Use `conda.plugins.virtual_packages.cuda.cuda_version` instead.",
         stack=+1,
     )
-    def cuda_version(self) -> Optional[str]:
-        """
-        Retrieves the current cuda version.
-        """
+    def cuda_version(self) -> str | None:
+        """Retrieves the current cuda version."""
         from conda.plugins.virtual_packages import cuda
 
         return cuda.cuda_version()
@@ -1956,7 +1946,6 @@ def determine_target_prefix(ctx, args=None):
     Returns: the prefix
     Raises: CondaEnvironmentNotFoundError if the prefix is invalid
     """
-
     argparse_args = args or ctx._argparse_args
     try:
         prefix_name = argparse_args.name

conda/cli/conda_argparse.py

@@ -354,17 +354,13 @@ def __call__(self, parser, namespace, values, option_string=None):
 
 
 def configure_parser_clean(sub_parsers):
-    descr = dedent(
-        """
-    Remove unused packages and caches.
-    """
-    )
-    example = dedent(
+    descr = "Remove unused packages and caches."
+    example = dals(
         """
-    Examples::
+        Examples::
 
-        conda clean --tarballs
-    """
+            conda clean --tarballs
+        """
     )
     p = sub_parsers.add_parser(
         "clean",

conda/cli/install.py

@@ -118,9 +118,7 @@ def get_revision(arg, json=False):
 
 
 def install(args, parser, command="install"):
-    """
-    conda install, conda update, and conda create
-    """
+    """Logic for `conda install`, `conda update`, and `conda create`."""
     context.validate_configuration()
     check_non_admin()
     # this is sort of a hack.  current_repodata.json may not have any .tar.bz2 files,

conda/cli/main_notices.py

@@ -7,9 +7,7 @@
 
 
 def execute(args: Namespace, _: ArgumentParser):
-    """
-    Command that retrieves channel notifications, caches them and displays them.
-    """
+    """Command that retrieves channel notifications, caches them and displays them."""
     try:
         channel_notice_set = notices.retrieve_notices()
     except OSError as exc:

conda/cli/main_package.py

@@ -18,9 +18,7 @@
 
 
 def remove(prefix, files):
-    """
-    Remove files for a given prefix.
-    """
+    """Remove files for a given prefix."""
     dst_dirs = set()
     for f in files:
         dst = join(prefix, f)
@@ -128,10 +126,7 @@ def _add_info_dir(t, tmp_dir, files, has_prefix, info):
 
 
 def create_conda_pkg(prefix, files, info, tar_path, update_info=None):
-    """
-    create a conda package with `files` (in `prefix` and `info` metadata)
-    at `tar_path`, and return a list of warning strings
-    """
+    """Create a conda package and return a list of warnings."""
     files = sorted(files)
     warnings = []
     has_prefix = []
@@ -193,9 +188,10 @@ def make_tarbz2(prefix, name="unknown", version="0.0", build_number=0, files=Non
 
 
 def which_package(path):
-    """
-    given the path (of a (presumably) conda installed file) iterate over
-    the conda packages the file came from.  Usually the iteration yields
+    """Return the package containing the path.
+
+    Provided the path of a (presumably) conda installed file, iterate over
+    the conda packages the file came from. Usually the iteration yields
     only one package.
     """
     path = abspath(path)
@@ -211,9 +207,10 @@ def which_package(path):
 
 
 def which_prefix(path):
-    """
-    given the path (to a (presumably) conda installed file) return the
-    environment prefix in which the file in located
+    """Return the prefix for the provided path.
+
+    Provided the path of a (presumably) conda installed file, return the
+    environment prefix in which the file in located.
     """
     prefix = abspath(path)
     while True:

conda/cli/main_rename.py

@@ -46,9 +46,7 @@ def validate_destination(dest: str, force: bool = False) -> str:
 
 
 def execute(args, _):
-    """
-    Executes the command for renaming an existing environment
-    """
+    """Executes the command for renaming an existing environment."""
     source = validate_src(args.name, args.prefix)
     destination = validate_destination(args.destination, force=args.force)
 

conda/common/_logic.py

@@ -23,9 +23,7 @@ def __init__(self):
         self.extend = self._clause_list.extend
 
     def get_clause_count(self):
-        """
-        Return number of stored clauses.
-        """
+        """Return number of stored clauses."""
         return len(self._clause_list)
 
     def save_state(self):
@@ -48,9 +46,7 @@ def as_list(self):
         return self._clause_list
 
     def as_array(self):
-        """
-        Return clauses as a flat int array, each clause being terminated by 0.
-        """
+        """Return clauses as a flat int array, each clause being terminated by 0."""
         clause_array = array("i")
         for c in self._clause_list:
             clause_array.extend(c)
@@ -115,16 +111,12 @@ def as_list(self):
                 clause.append(v)
 
     def as_array(self):
-        """
-        Return clauses as a flat int array, each clause being terminated by 0.
-        """
+        """Return clauses as a flat int array, each clause being terminated by 0."""
         return self._clause_array
 
 
 class _SatSolver:
-    """
-    Simple wrapper to call a SAT solver given a _ClauseList/_ClauseArray instance.
-    """
+    """Simple wrapper to call a SAT solver given a _ClauseList/_ClauseArray instance."""
 
     def __init__(self, **run_kwargs):
         self._run_kwargs = run_kwargs or {}

conda/common/_os/linux.py

@@ -12,10 +12,7 @@
 
 @lru_cache(maxsize=None)
 def linux_get_libc_version():
-    """
-    If on linux, returns (libc_family, version), otherwise (None, None).
-    """
-
+    """If on linux, returns (libc_family, version), otherwise (None, None)."""
     if not sys.platform.startswith("linux"):
         return None, None