Add opt-in support for --skip-existing on non-PyPI repositories

Author: John Pocock

AUTHORS

@@ -33,3 +33,4 @@ Cyril de Catheu <cdecatheu@gmail.com> (https://catheu.tech/)
 Thomas Miedema <thomasmiedema@gmail.com>
 Hugo van Kemenade (https://github.com/hugovk)
 Jacob Woliver <jacob@jmw.sh> (jmw.sh)
+John Pocock <john.oss@pocock.io>

changelog/XXXX.feature.rst

@@ -0,0 +1 @@
+Add opt-in support for ``--skip-existing`` on non-PyPI repositories via the ``--skip-existing-non-pypi`` CLI flag or ``TWINE_SKIP_EXISTING_NON_PYPI`` environment variable, enabling testing scenarios and support for PEP 694-compliant third-party registries.

docs/index.rst

@@ -164,6 +164,8 @@ on a CI/build server).
   self-signed or untrusted certificates.
 * ``TWINE_NON_INTERACTIVE`` - Do not interactively prompt for username/password
   if the required credentials are missing.
+* ``TWINE_SKIP_EXISTING_NON_PYPI`` - Allow ``--skip-existing`` to work with
+  non-PyPI repositories. Set to ``1`` or ``true`` to enable.
 
 Proxy Support
 ^^^^^^^^^^^^^

tests/test_settings.py

@@ -115,6 +115,62 @@ def test_settings_verify_feature_compatibility() -> None:
         )
 
 
+def test_settings_verify_feature_compatibility_with_flag() -> None:
+    """Test that skip_existing_non_pypi parameter allows skip-existing for non-PyPI."""
+    # Without the flag, should raise
+    s = settings.Settings(skip_existing=True, skip_existing_non_pypi=False)
+    s.repository_config = {"repository": "https://not-pypi.example.com/legacy"}
+    with pytest.raises(exceptions.UnsupportedConfiguration):
+        s.verify_feature_capability()
+
+    # With the flag set to True, should not raise
+    s = settings.Settings(skip_existing=True, skip_existing_non_pypi=True)
+    s.repository_config = {"repository": "https://not-pypi.example.com/legacy"}
+    try:
+        s.verify_feature_capability()
+    except exceptions.UnsupportedConfiguration as unexpected_exc:
+        pytest.fail(
+            "Expected skip-existing to work with non-PyPI when "
+            f"skip_existing_non_pypi=True but got {unexpected_exc!r}"
+        )
+
+
+def test_settings_skip_existing_non_pypi_still_works_for_pypi() -> None:
+    """Test that PyPI and TestPyPI work regardless of skip_existing_non_pypi flag."""
+    # PyPI should work without the flag
+    s = settings.Settings(skip_existing=True, skip_existing_non_pypi=False)
+    s.repository_config = {"repository": repository.WAREHOUSE}
+    try:
+        s.verify_feature_capability()
+    except exceptions.UnsupportedConfiguration as unexpected_exc:
+        pytest.fail(
+            "Expected PyPI to work without skip_existing_non_pypi "
+            f"but got {unexpected_exc!r}"
+        )
+
+    # TestPyPI should work without the flag
+    s = settings.Settings(skip_existing=True, skip_existing_non_pypi=False)
+    s.repository_config = {"repository": repository.TEST_WAREHOUSE}
+    try:
+        s.verify_feature_capability()
+    except exceptions.UnsupportedConfiguration as unexpected_exc:
+        pytest.fail(
+            "Expected TestPyPI to work without skip_existing_non_pypi "
+            f"but got {unexpected_exc!r}"
+        )
+
+    # PyPI should still work with the flag
+    s = settings.Settings(skip_existing=True, skip_existing_non_pypi=True)
+    s.repository_config = {"repository": repository.WAREHOUSE}
+    try:
+        s.verify_feature_capability()
+    except exceptions.UnsupportedConfiguration as unexpected_exc:
+        pytest.fail(
+            "Expected PyPI to work with skip_existing_non_pypi "
+            f"but got {unexpected_exc!r}"
+        )
+
+
 @pytest.mark.parametrize(
     "verbose, log_level", [(True, logging.INFO), (False, logging.WARNING)]
 )
@@ -202,3 +258,15 @@ def test_non_interactive_environment(self, monkeypatch):
     def test_attestations_flag(self):
         args = self.parse_args(["--attestations"])
         assert args.attestations
+
+    def test_skip_existing_non_pypi_flag(self):
+        args = self.parse_args(["--skip-existing-non-pypi"])
+        assert args.skip_existing_non_pypi
+
+    def test_skip_existing_non_pypi_environment(self, monkeypatch):
+        monkeypatch.setenv("TWINE_SKIP_EXISTING_NON_PYPI", "1")
+        args = self.parse_args([])
+        assert args.skip_existing_non_pypi
+        monkeypatch.setenv("TWINE_SKIP_EXISTING_NON_PYPI", "0")
+        args = self.parse_args([])
+        assert not args.skip_existing_non_pypi

twine/settings.py

@@ -55,6 +55,7 @@ def __init__(
         comment: Optional[str] = None,
         config_file: str = utils.DEFAULT_CONFIG_FILE,
         skip_existing: bool = False,
+        skip_existing_non_pypi: bool = False,
         cacert: Optional[str] = None,
         client_cert: Optional[str] = None,
         repository_name: str = "pypi",
@@ -90,6 +91,9 @@ def __init__(
             Specify whether twine should continue uploading files if one
             of them already exists. This primarily supports PyPI. Other
             package indexes may not be supported.
+        :param skip_existing_non_pypi:
+            Allow --skip-existing to work with non-PyPI repositories.
+            Use at your own risk with third-party registries.
         :param cacert:
             The path to the bundle of certificates used to verify the TLS
             connection to the package index.
@@ -113,6 +117,7 @@ def __init__(
         self.verbose = verbose
         self.disable_progress_bar = disable_progress_bar
         self.skip_existing = skip_existing
+        self.skip_existing_non_pypi = skip_existing_non_pypi
         self._handle_repository_options(
             repository_name=repository_name,
             repository_url=repository_url,
@@ -245,9 +250,18 @@ def register_argparse_arguments(parser: argparse.ArgumentParser) -> None:
             default=False,
             action="store_true",
             help="Continue uploading files if one already exists. (Only valid "
-            "when uploading to PyPI. Other implementations may not "
+            "when uploading to PyPI by default. For other repositories, use "
+            "--skip-existing-non-pypi flag. Other implementations may not "
             "support this.)",
         )
+        parser.add_argument(
+            "--skip-existing-non-pypi",
+            action=utils.EnvironmentFlag,
+            env="TWINE_SKIP_EXISTING_NON_PYPI",
+            help="Allow --skip-existing to work with non-PyPI repositories. "
+            "Use at your own risk with third-party registries. (Can also be "
+            "set via %(env)s environment variable.)",
+        )
         parser.add_argument(
             "--cert",
             action=utils.EnvironmentDefault,
@@ -317,7 +331,10 @@ def verify_feature_capability(self) -> None:
         """Verify configured settings are supported for the configured repository.
 
         This presently checks:
-        - ``--skip-existing`` was only provided for PyPI and TestPyPI
+
+        - ``--skip-existing`` was only provided for PyPI and TestPyPI, unless
+          explicitly allowed via --skip-existing-non-pypi flag or
+          TWINE_SKIP_EXISTING_NON_PYPI environment variable
 
         :raises twine.exceptions.UnsupportedConfiguration:
             The configured features are not available with the configured
@@ -328,9 +345,15 @@ def verify_feature_capability(self) -> None:
         if self.skip_existing and not repository_url.startswith(
             (repository.WAREHOUSE, repository.TEST_WAREHOUSE)
         ):
-            raise exceptions.UnsupportedConfiguration.Builder().with_feature(
-                "--skip-existing"
-            ).with_repository_url(repository_url).finalize()
+            # Allow opt-in for non-PyPI repositories (e.g., for testing or
+            # third-party registries that support PEP 694's 409 response)
+            if not self.skip_existing_non_pypi:
+                raise (
+                    exceptions.UnsupportedConfiguration.Builder()
+                    .with_feature("--skip-existing")
+                    .with_repository_url(repository_url)
+                    .finalize()
+                )
 
     def check_repository_url(self) -> None:
         """Verify we are not using legacy PyPI.