Fix ls/rm docstrings across v3/v4

b2/_internal/_cli/b2args.py

@@ -44,13 +44,14 @@ def b2_uri(value: str) -> B2URI:
 
 def add_b2_uri_argument(parser: argparse.ArgumentParser, name="B2_URI"):
     """
-    Add a B2 URI pointing to a file as an argument to the parser.
+    Add a B2 URI pointing to a bucket, optionally with a directory
+    or a pattern as an argument to the parser.
     """
     parser.add_argument(
         name,
         type=B2_URI_ARG_TYPE,
         help="B2 URI pointing to a bucket, directory or a pattern, "
-        "e.g. b2://yourBucket, b2://yourBucket/file.txt, b2://yourBucket/folder, "
+        "e.g. b2://yourBucket, b2://yourBucket/file.txt, b2://yourBucket/folder/, "
         "b2://yourBucket/*.txt or b2id://fileId",
     )
 

b2/_internal/b2v3/registry.py

@@ -14,8 +14,42 @@
 
 
 class Ls(B2URIBucketNFolderNameArgMixin, BaseLs):
-    __doc__ = BaseLs.__doc__
-    # TODO: fix doc
+    """
+    {BASELS}
+
+    Examples
+
+    .. note::
+
+        Note the use of quotes, to ensure that special
+        characters are not expanded by the shell.
+
+
+    List csv and tsv files (in any directory, in the whole bucket):
+
+    .. code-block::
+
+        {NAME} ls --recursive --withWildcard bucketName "*.[ct]sv"
+
+
+    List all info.txt files from buckets bX, where X is any character:
+
+    .. code-block::
+
+        {NAME} ls --recursive --withWildcard bucketName "b?/info.txt"
+
+
+    List all pdf files from buckets b0 to b9 (including sub-directories):
+
+    .. code-block::
+
+        {NAME} ls --recursive --withWildcard bucketName "b[0-9]/*.pdf"
+
+
+    Requires capability:
+
+    - **listFiles**
+    """
 
 
 B2.register_subcommand(AuthorizeAccount)

b2/_internal/b2v3/rm.py

@@ -15,5 +15,45 @@
 # NOTE: We need to keep v3 Rm in separate file, because we need to import it in
 # unit tests without registering any commands.
 class Rm(B2URIBucketNFolderNameArgMixin, BaseRm):
-    __doc__ = BaseRm.__doc__
-    # TODO: fix doc
+    """
+        {BASERM}
+
+        Examples.
+
+    .. note::
+
+        Note the use of quotes, to ensure that special
+        characters are not expanded by the shell.
+
+
+    .. note::
+
+        Use with caution. Running examples presented below can cause data-loss.
+
+
+    Remove all csv and tsv files (in any directory, in the whole bucket):
+
+    .. code-block::
+
+        {NAME} rm --recursive --withWildcard bucketName "*.[ct]sv"
+
+
+    Remove all info.txt files from buckets bX, where X is any character:
+
+    .. code-block::
+
+        {NAME} rm --recursive --withWildcard bucketName "b?/info.txt"
+
+
+    Remove all pdf files from buckets b0 to b9 (including sub-directories):
+
+    .. code-block::
+
+        {NAME} rm --recursive --withWildcard bucketName "b[0-9]/*.pdf"
+
+
+        Requires capability:
+
+        - **listFiles**
+        - **deleteFiles**
+        """

b2/_internal/console_tool.py

@@ -2227,39 +2227,6 @@ class BaseLs(AbstractLsCommand, metaclass=ABCMeta):
     The ``--replication`` option adds replication status
 
     {ABSTRACTLSCOMMAND}
-
-    Examples
-
-    .. note::
-
-        Note the use of quotes, to ensure that special
-        characters are not expanded by the shell.
-
-
-    List csv and tsv files (in any directory, in the whole bucket):
-
-    .. code-block::
-
-        {NAME} ls --recursive --withWildcard bucketName "*.[ct]sv"
-
-
-    List all info.txt files from buckets bX, where X is any character:
-
-    .. code-block::
-
-        {NAME} ls --recursive --withWildcard bucketName "b?/info.txt"
-
-
-    List all pdf files from buckets b0 to b9 (including sub-directories):
-
-    .. code-block::
-
-        {NAME} ls --recursive --withWildcard bucketName "b[0-9]/*.pdf"
-
-
-    Requires capability:
-
-    - **listFiles**
     """
 
     # order is file_id, action, date, time, size(, replication), name
@@ -2328,7 +2295,42 @@ def format_ls_entry(self, file_version: FileVersion, replication: bool):
 
 
 class Ls(B2URIMixin, BaseLs):
-    __doc__ = BaseLs.__doc__
+    """
+    {BASELS}
+
+    Examples
+
+    .. note::
+
+        Note the use of quotes, to ensure that special
+        characters are not expanded by the shell.
+
+
+    List csv and tsv files (in any directory, in the whole bucket):
+
+    .. code-block::
+
+        {NAME} ls --recursive --withWildcard "b2://bucketName/*.[ct]sv"
+
+
+    List all info.txt files from buckets bX, where X is any character:
+
+    .. code-block::
+
+        {NAME} ls --recursive --withWildcard "b2://bucketName/b?/info.txt"
+
+
+    List all pdf files from buckets b0 to b9 (including sub-directories):
+
+    .. code-block::
+
+        {NAME} ls --recursive --withWildcard "b2://bucketName/b[0-9]/*.pdf"
+
+
+    Requires capability:
+
+    - **listFiles**
+    """
 
 
 class BaseRm(ThreadsMixin, AbstractLsCommand, metaclass=ABCMeta):
@@ -2368,45 +2370,6 @@ class BaseRm(ThreadsMixin, AbstractLsCommand, metaclass=ABCMeta):
 
     Command returns 0 if all files were removed successfully and
     a value different from 0 if any file was left.
-
-    Examples.
-
-    .. note::
-
-        Note the use of quotes, to ensure that special
-        characters are not expanded by the shell.
-
-
-    .. note::
-
-        Use with caution. Running examples presented below can cause data-loss.
-
-
-    Remove all csv and tsv files (in any directory, in the whole bucket):
-
-    .. code-block::
-
-        {NAME} rm --recursive --withWildcard bucketName "*.[ct]sv"
-
-
-    Remove all info.txt files from buckets bX, where X is any character:
-
-    .. code-block::
-
-        {NAME} rm --recursive --withWildcard bucketName "b?/info.txt"
-
-
-    Remove all pdf files from buckets b0 to b9 (including sub-directories):
-
-    .. code-block::
-
-        {NAME} rm --recursive --withWildcard bucketName "b[0-9]/*.pdf"
-
-
-    Requires capability:
-
-    - **listFiles**
-    - **deleteFiles**
     """
 
     PROGRESS_REPORT_CLASS = ProgressReport
@@ -2501,7 +2464,6 @@ def _setup_parser(cls, parser):
         )
         parser.add_argument('--noProgress', action='store_true')
         parser.add_argument('--failFast', action='store_true')
-        # TODO: --bypassGovernance
         super()._setup_parser(parser)
 
     def _run(self, args):
@@ -2540,7 +2502,48 @@ def _run(self, args):
 
 
 class Rm(B2URIMixin, BaseRm):
-    __doc__ = BaseRm.__doc__
+    """
+    {BASERM}
+
+    Examples.
+
+        .. note::
+
+            Note the use of quotes, to ensure that special
+            characters are not expanded by the shell.
+
+
+        .. note::
+
+            Use with caution. Running examples presented below can cause data-loss.
+
+
+        Remove all csv and tsv files (in any directory, in the whole bucket):
+
+        .. code-block::
+
+            {NAME} rm --recursive --withWildcard "b2://bucketName/*.[ct]sv"
+
+
+        Remove all info.txt files from buckets bX, where X is any character:
+
+        .. code-block::
+
+            {NAME} rm --recursive --withWildcard "b2://bucketName/b?/info.txt"
+
+
+        Remove all pdf files from buckets b0 to b9 (including sub-directories):
+
+        .. code-block::
+
+            {NAME} rm --recursive --withWildcard "b2://bucketName/b[0-9]/*.pdf"
+
+
+    Requires capability:
+
+    - **listFiles**
+    - **deleteFiles**
+    """
 
 
 class GetUrlBase(Command):