ApiVer introduced into CLI

- `b2`, `b2v3` and unstable `_b2v4` scripts and binaries are now built.
- Tests are ran against all available versions.
- Both unit and integration tests have the ability to limit versions
  on which given tests are running.
- `doc` is built only for the latest stable version.
- Implementation moved to `_internal` to discourage people from importing it.

.github/workflows/ci.yml

@@ -167,7 +167,7 @@ jobs:
         id: hashes
         run: nox -vs make_dist_digest
       - name: Run integration tests (without secrets)
-        run: nox -vs integration -- -m "not require_secrets"
+        run: nox -vs integration -- --sut=${{ steps.bundle.outputs.sut_path }} -m "not require_secrets"
       - name: Run integration tests (with secrets)
         if: ${{ env.B2_TEST_APPLICATION_KEY != '' && env.B2_TEST_APPLICATION_KEY_ID != '' }}
         run: nox -vs integration -- --sut=${{ steps.bundle.outputs.sut_path }} -m "require_secrets" --cleanup
@@ -206,7 +206,7 @@ jobs:
         id: hashes
         run: nox -vs make_dist_digest
       - name: Run integration tests (without secrets)
-        run: nox -vs integration -- -m "not require_secrets"
+        run: nox -vs integration -- --sut=${{ steps.bundle.outputs.sut_path }} -m "not require_secrets"
       - name: Run integration tests (with secrets)
         if: ${{ env.B2_TEST_APPLICATION_KEY != '' && env.B2_TEST_APPLICATION_KEY_ID != '' }}
         run: nox -vs integration -- --sut=${{ steps.bundle.outputs.sut_path }} -m "require_secrets" --cleanup

.gitignore

@@ -14,3 +14,4 @@ venv
 doc/source/main_help.rst
 Dockerfile
 b2/licenses_output.txt
+*.spec

README.md

@@ -155,6 +155,26 @@ or by mounting local files in the docker container:
 docker run --rm -v b2:/root -v /home/user/path/to/data:/data backblazeit/b2:latest upload-file bucket_name /data/source_file.txt target_file_name
 ```
 
+## Versions
+
+When you start working with `b2`, you might notice that more than one script is available to you.
+This is by design - we use the `ApiVer` methodology to provide all the commands to all the versions
+while also providing all the bugfixes to all the old versions.
+
+If you use the `b2` command, you're working with the latest stable version.
+It provides all the bells and whistles, latest features, and the best performance.
+While it's a great version to work with, if you're willing to write a reliable, long-running script,
+you might find out that after some time it will break.
+New commands will appear, older will deprecate and be removed, parameters will change.
+Backblaze service evolves and the `b2` CLI evolves with it.
+
+However, now you have a way around this problem.
+Instead of using the `b2` command, you can use a version-bound interface e.g.: `b2v3`.
+This command will always provide the same interface that the `ApiVer` version `3` provided.
+Even if the `b2` command goes into the `ApiVer` version `4`, `6` or even `10` with some major changes,
+`b2v3` will still provide the same interface, same commands, and same parameters.
+Over time, it might get slower as we may need to emulate some older behaviors, but we'll ensure that it won't break.
+
 ## Contrib
 
 ### Detailed logs

b2.spec → b2.spec.template

@@ -8,7 +8,7 @@ block_cipher = None
 # https://github.com/Backblaze/B2_Command_Line_Tool/issues/689
 datas = copy_metadata('b2') + collect_data_files('dateutil')
 
-a = Analysis(['b2/console_tool.py'],
+a = Analysis(['b2/_internal/${VERSION}/__main__.py'],
              pathex=['.'],
              binaries=[],
              datas=datas,
@@ -30,7 +30,7 @@ exe = EXE(pyz,
           a.zipfiles,
           a.datas,
           [],
-          name='b2',
+          name='${NAME}',
           debug=False,
           bootloader_ignore_signals=False,
           strip=False,

b2/__init__.py

@@ -13,7 +13,7 @@
 
 logging.getLogger(__name__).addHandler(logging.NullHandler())
 
-import b2.version  # noqa: E402
+import b2._internal.version  # noqa: E402
 
-__version__ = b2.version.VERSION
+__version__ = b2._internal.version.VERSION
 assert __version__  # PEP-0396

b2/_utils/__init__.py → b2/_internal/__init__.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/_utils/__init__.py
+# File: b2/_internal/__init__.py
 #
 # Copyright 2023 Backblaze Inc. All Rights Reserved.
 #

b2/_internal/_b2v4/__init__.py

@@ -0,0 +1,11 @@
+######################################################################
+#
+# File: b2/_internal/_b2v4/__init__.py
+#
+# Copyright 2023 Backblaze Inc. All Rights Reserved.
+#
+# License https://www.backblaze.com/using_b2_code.html
+#
+######################################################################
+
+# Note: importing console_tool in any shape or form in here will break sys.argv.

b2/_internal/_b2v4/__main__.py

@@ -0,0 +1,13 @@
+######################################################################
+#
+# File: b2/_internal/_b2v4/__main__.py
+#
+# Copyright 2023 Backblaze Inc. All Rights Reserved.
+#
+# License https://www.backblaze.com/using_b2_code.html
+#
+######################################################################
+
+from b2._internal._b2v4.registry import main
+
+main()

b2/_internal/_b2v4/registry.py

@@ -0,0 +1,57 @@
+######################################################################
+#
+# File: b2/_internal/_b2v4/registry.py
+#
+# Copyright 2023 Backblaze Inc. All Rights Reserved.
+#
+# License https://www.backblaze.com/using_b2_code.html
+#
+######################################################################
+
+# ruff: noqa: F405
+from b2._internal.console_tool import *  # noqa
+
+B2.register_subcommand(AuthorizeAccount)
+B2.register_subcommand(CancelAllUnfinishedLargeFiles)
+B2.register_subcommand(CancelLargeFile)
+B2.register_subcommand(ClearAccount)
+B2.register_subcommand(CopyFileById)
+B2.register_subcommand(CreateBucket)
+B2.register_subcommand(CreateKey)
+B2.register_subcommand(DeleteBucket)
+B2.register_subcommand(DeleteFileVersion)
+B2.register_subcommand(DeleteKey)
+B2.register_subcommand(DownloadFile)
+B2.register_subcommand(DownloadFileById)
+B2.register_subcommand(DownloadFileByName)
+B2.register_subcommand(Cat)
+B2.register_subcommand(GetAccountInfo)
+B2.register_subcommand(GetBucket)
+B2.register_subcommand(FileInfo)
+B2.register_subcommand(GetFileInfo)
+B2.register_subcommand(GetDownloadAuth)
+B2.register_subcommand(GetDownloadUrlWithAuth)
+B2.register_subcommand(HideFile)
+B2.register_subcommand(ListBuckets)
+B2.register_subcommand(ListKeys)
+B2.register_subcommand(ListParts)
+B2.register_subcommand(ListUnfinishedLargeFiles)
+B2.register_subcommand(Ls)
+B2.register_subcommand(Rm)
+B2.register_subcommand(GetUrl)
+B2.register_subcommand(MakeUrl)
+B2.register_subcommand(MakeFriendlyUrl)
+B2.register_subcommand(Sync)
+B2.register_subcommand(UpdateBucket)
+B2.register_subcommand(UploadFile)
+B2.register_subcommand(UploadUnboundStream)
+B2.register_subcommand(UpdateFileLegalHold)
+B2.register_subcommand(UpdateFileRetention)
+B2.register_subcommand(ReplicationSetup)
+B2.register_subcommand(ReplicationDelete)
+B2.register_subcommand(ReplicationPause)
+B2.register_subcommand(ReplicationUnpause)
+B2.register_subcommand(ReplicationStatus)
+B2.register_subcommand(Version)
+B2.register_subcommand(License)
+B2.register_subcommand(InstallAutocomplete)

b2/_cli/__init__.py → b2/_internal/_cli/__init__.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/_cli/__init__.py
+# File: b2/_internal/_cli/__init__.py
 #
 # Copyright 2023 Backblaze Inc. All Rights Reserved.
 #
@@ -11,4 +11,4 @@
 _cli package contains internals of the command-line interface to the B2.
 
 It is not intended to be used as a library.
-"""
+"""

b2/_cli/arg_parser_types.py → b2/_internal/_cli/arg_parser_types.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/_cli/arg_parser_types.py
+# File: b2/_internal/_cli/arg_parser_types.py
 #
 # Copyright 2020 Backblaze Inc. All Rights Reserved.
 #
@@ -75,4 +75,4 @@ def wrapper(*args, **kwargs):
         except exc_type as e:
             raise argparse.ArgumentTypeError(translator(e))
 
-    return wrapper
+    return wrapper

b2/_cli/argcompleters.py → b2/_internal/_cli/argcompleters.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/_cli/argcompleters.py
+# File: b2/_internal/_cli/argcompleters.py
 #
 # Copyright 2023 Backblaze Inc. All Rights Reserved.
 #
@@ -16,7 +16,7 @@
 
 
 def bucket_name_completer(prefix, parsed_args, **kwargs):
-    from b2._cli.b2api import _get_b2api_for_profile
+    from b2._internal._cli.b2api import _get_b2api_for_profile
     api = _get_b2api_for_profile(getattr(parsed_args, 'profile', None))
     res = [bucket.name for bucket in api.list_buckets(use_cache=True)]
     return res
@@ -30,7 +30,7 @@ def file_name_completer(prefix, parsed_args, **kwargs):
     """
     from b2sdk.v2 import LIST_FILE_NAMES_MAX_LIMIT
 
-    from b2._cli.b2api import _get_b2api_for_profile
+    from b2._internal._cli.b2api import _get_b2api_for_profile
 
     api = _get_b2api_for_profile(parsed_args.profile)
     bucket = api.get_bucket_by_name(parsed_args.bucketName)
@@ -52,9 +52,9 @@ def b2uri_file_completer(prefix: str, parsed_args, **kwargs):
     """
     from b2sdk.v2 import LIST_FILE_NAMES_MAX_LIMIT
 
-    from b2._cli.b2api import _get_b2api_for_profile
-    from b2._utils.python_compat import removeprefix
-    from b2._utils.uri import parse_b2_uri
+    from b2._internal._cli.b2api import _get_b2api_for_profile
+    from b2._internal._utils.python_compat import removeprefix
+    from b2._internal._utils.uri import parse_b2_uri
 
     api = _get_b2api_for_profile(getattr(parsed_args, 'profile', None))
     if prefix.startswith('b2://'):

b2/_cli/autocomplete_cache.py → b2/_internal/_cli/autocomplete_cache.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/_cli/autocomplete_cache.py
+# File: b2/_internal/_cli/autocomplete_cache.py
 #
 # Copyright 2020 Backblaze Inc. All Rights Reserved.
 #
@@ -19,7 +19,7 @@
 import argcomplete
 import platformdirs
 
-from b2.version import VERSION
+from b2._internal.version import VERSION
 
 
 def identity(x):

b2/_cli/autocomplete_install.py → b2/_internal/_cli/autocomplete_install.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/_cli/autocomplete_install.py
+# File: b2/_internal/_cli/autocomplete_install.py
 #
 # Copyright 2023 Backblaze Inc. All Rights Reserved.
 #
@@ -157,4 +157,4 @@ class AutocompleteInstallError(Exception):
     """Exception raised when autocomplete installation fails."""
 
 
-SUPPORTED_SHELLS = sorted(SHELL_REGISTRY.keys())
+SUPPORTED_SHELLS = sorted(SHELL_REGISTRY.keys())

b2/_cli/b2api.py → b2/_internal/_cli/b2api.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/_cli/b2api.py
+# File: b2/_internal/_cli/b2api.py
 #
 # Copyright 2023 Backblaze Inc. All Rights Reserved.
 #
@@ -18,7 +18,7 @@
     SqliteAccountInfo,
 )
 
-from b2._cli.const import B2_USER_AGENT_APPEND_ENV_VAR
+from b2._internal._cli.const import B2_USER_AGENT_APPEND_ENV_VAR
 
 
 def _get_b2api_for_profile(profile: Optional[str] = None, **kwargs) -> B2Api:

b2/_cli/b2args.py → b2/_internal/_cli/b2args.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/_cli/b2args.py
+# File: b2/_internal/_cli/b2args.py
 #
 # Copyright 2023 Backblaze Inc. All Rights Reserved.
 #
@@ -12,9 +12,9 @@
 """
 import argparse
 
-from b2._cli.arg_parser_types import wrap_with_argument_type_error
-from b2._cli.argcompleters import b2uri_file_completer
-from b2._utils.uri import B2URI, B2URIBase, parse_b2_uri
+from b2._internal._cli.arg_parser_types import wrap_with_argument_type_error
+from b2._internal._cli.argcompleters import b2uri_file_completer
+from b2._internal._utils.uri import B2URI, B2URIBase, parse_b2_uri
 
 
 def b2_file_uri(value: str) -> B2URIBase:

b2/_cli/const.py → b2/_internal/_cli/const.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/_cli/const.py
+# File: b2/_internal/_cli/const.py
 #
 # Copyright 2023 Backblaze Inc. All Rights Reserved.
 #

b2/_cli/obj_loads.py → b2/_internal/_cli/obj_loads.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/_cli/obj_loads.py
+# File: b2/_internal/_cli/obj_loads.py
 #
 # Copyright 2023 Backblaze Inc. All Rights Reserved.
 #

b2/_cli/shell.py → b2/_internal/_cli/shell.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/_cli/shell.py
+# File: b2/_internal/_cli/shell.py
 #
 # Copyright 2023 Backblaze Inc. All Rights Reserved.
 #

b2/__main__.py → b2/_internal/_utils/__init__.py

@@ -1,13 +1,9 @@
 ######################################################################
 #
-# File: b2/__main__.py
+# File: b2/_internal/_utils/__init__.py
 #
-# Copyright 2019 Backblaze Inc. All Rights Reserved.
+# Copyright 2023 Backblaze Inc. All Rights Reserved.
 #
 # License https://www.backblaze.com/using_b2_code.html
 #
 ######################################################################
-
-from .console_tool import main
-
-main()

b2/_utils/python_compat.py → b2/_internal/_utils/python_compat.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/_utils/python_compat.py
+# File: b2/_internal/_utils/python_compat.py
 #
 # Copyright 2023 Backblaze Inc. All Rights Reserved.
 #

b2/_utils/uri.py → b2/_internal/_utils/uri.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/_utils/uri.py
+# File: b2/_internal/_utils/uri.py
 #
 # Copyright 2023 Backblaze Inc. All Rights Reserved.
 #
@@ -20,7 +20,7 @@
     FileVersion,
 )
 
-from b2._utils.python_compat import removeprefix, singledispatchmethod
+from b2._internal._utils.python_compat import removeprefix, singledispatchmethod
 
 
 class B2URIBase:

b2/arg_parser.py → b2/_internal/arg_parser.py

@@ -1,6 +1,6 @@
 ######################################################################
 #
-# File: b2/arg_parser.py
+# File: b2/_internal/arg_parser.py
 #
 # Copyright 2020 Backblaze Inc. All Rights Reserved.
 #

b2/_internal/b2v3/__init__.py

@@ -0,0 +1,11 @@
+######################################################################
+#
+# File: b2/_internal/b2v3/__init__.py
+#
+# Copyright 2023 Backblaze Inc. All Rights Reserved.
+#
+# License https://www.backblaze.com/using_b2_code.html
+#
+######################################################################
+
+# Note: importing console_tool in any shape or form in here will break sys.argv.