disable keyring per default and only install via an extra

Author: radoering

docs/_index.md

@@ -58,6 +58,15 @@ Any non-ancient version of `pipx` will do.
 ```bash
 pipx install poetry
 ```
+
+If you want to use a keyring for storing credentials, you can install Poetry with its `keyring` extra:
+
+```bash
+pipx install poetry[keyring]
+```
+
+See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}})
+for more information.
 {{< /step >}}
 {{< step >}}
 **Install Poetry (advanced)**

docs/configuration.md

@@ -234,7 +234,7 @@ across all your projects if incorrectly set.
 
 **Environment Variable**: `POETRY_INSTALLER_ONLY_BINARY`
 
-*Introduced in 1.9.0*
+*Introduced in 2.0.0*
 
 When set, this configuration allows users to enforce the use of binary distribution format for all, none or
 specific packages.
@@ -502,10 +502,13 @@ for more information.
 
 **Type**: `boolean`
 
-**Default**: `true`
+**Default**: `false`
 
 **Environment Variable**: `POETRY_KEYRING_ENABLED`
 
+*Changed default to `false` in 2.0.0*
+
 Enable the system keyring for storing credentials.
+(Requires Poetry to be installed with the `keyring` extra.)
 See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}})
 for more information.

docs/repositories.md

@@ -472,16 +472,20 @@ poetry config http-basic.pypi <username> <password>
 You can also specify the username and password when using the `publish` command
 with the `--username` and `--password` options.
 
-If a system keyring is available and supported, the password is stored to and retrieved from the keyring. In the above example, the credential will be stored using the name `poetry-repository-pypi`. If access to keyring fails or is unsupported, this will fall back to writing the password to the `auth.toml` file along with the username.
-
-Keyring support is enabled using the [keyring library](https://pypi.org/project/keyring/). For more information on supported backends refer to the [library documentation](https://keyring.readthedocs.io/en/latest/?badge=latest).
-
-If you do not want to use the keyring, you can tell Poetry to disable it and store the credentials in plaintext config files:
+If a system keyring is available and supported, the password is stored to and retrieved from the keyring.
+Otherwise, credentials are stored in plaintext config files.
+In order to use keyring, you have to install Poetry with its `keyring` extra (`poetry[keyring]`)
+and enable keyring support:
 
 ```bash
-poetry config keyring.enabled false
+poetry config keyring.enabled true
 ```
 
+In the above example, the credential will be stored using the name `poetry-repository-pypi`.
+If access to keyring is disabled, fails or is unsupported, this will fall back to writing the password to the `auth.toml` file along with the username.
+
+Keyring support is enabled using the [keyring library](https://pypi.org/project/keyring/). For more information on supported backends refer to the [library documentation](https://keyring.readthedocs.io/en/latest/?badge=latest).
+
 {{% note %}}
 
 Poetry will fall back to Pip style use of keyring so that backends like

poetry.lock

@@ -39,7 +39,7 @@ dulwich = "^0.22.1"
 fastjsonschema = "^2.18.0"
 importlib-metadata = { version = ">=4.4", python = "<3.10" }
 installer = "^0.7.0"
-keyring = "^25.1.0"
+keyring = { version = "^25.1.0", optional = true }
 # packaging uses calver, so version is unclamped
 packaging = ">=24.0"
 pkginfo = "^1.10"
@@ -55,6 +55,9 @@ trove-classifiers = ">=2022.5.19"
 virtualenv = "^20.26.6"
 xattr = { version = "^1.0.0", markers = "sys_platform == 'darwin'" }
 
+[tool.poetry.extras]
+keyring = [ "keyring" ]
+
 [tool.poetry.group.dev.dependencies]
 pre-commit = ">=2.10"
 # add setuptools for PyCharm
@@ -66,6 +69,7 @@ setuptools = { version = ">=60", python = "<3.10" }
 coverage = ">=7.2.0"
 deepdiff = ">=6.3"
 httpretty = ">=1.1"
+keyring = "*"  # version is constrained via extra
 jaraco-classes = ">=3.3.1"
 pytest = ">=8.0"
 pytest-cov = ">=4.0"
@@ -132,8 +136,19 @@ unfixable = [
     "ERA", # do not autoremove commented out code
 ]
 
+[tool.ruff.lint.per-file-ignores]
+# keyring is an extra and must only be imported in password_manager.py
+# and even there not globally
+# see flake8-tidy-imports.banned-api and .banned-module-level-imports settings
+"password_manager.py" = ["TID251"]
+"tests/*" = ["TID251", "TID253"]
+
 [tool.ruff.lint.flake8-tidy-imports]
 ban-relative-imports = "all"
+banned-module-level-imports = ["keyring"]  # because it is an extra
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"keyring".msg = "keyring imports are only allowed in password_manager.py"
 
 [tool.ruff.lint.isort]
 force-single-line = true

pyproject.toml

@@ -133,7 +133,7 @@ class Config:
         },
         "system-git-client": False,
         "keyring": {
-            "enabled": True,
+            "enabled": False,
         },
     }
 

src/poetry/config/config.py

@@ -154,7 +154,12 @@ def keyring(self) -> PoetryKeyring:
 
     @staticmethod
     def warn_plaintext_credentials_stored() -> None:
-        logger.warning("Using a plaintext file to store credentials")
+        logger.warning(
+            "Using a plaintext file to store credentials.\n"
+            "Install Poetry with its `keyring` extra (`poetry[keyring]`)"
+            "and enable it (`poetry config keyring.enabled true`)"
+            " to store credentials securely."
+        )
 
     def set_pypi_token(self, repo_name: str, token: str) -> None:
         if not self.use_keyring:

src/poetry/utils/password_manager.py

@@ -111,6 +111,10 @@ def test_config_expands_tilde_for_virtualenvs_path(
 def test_disabled_keyring_is_unavailable(
     config: Config, with_simple_keyring: None, dummy_keyring: DummyBackend
 ) -> None:
+    manager = PasswordManager(config)
+    assert not manager.use_keyring
+
+    config.config["keyring"]["enabled"] = True
     manager = PasswordManager(config)
     assert manager.use_keyring