AWS CodeArtifact Keyring Backend

Warnings

• gotcha The `keyrings.codeartifact` package functions as a backend for the `keyring` library. Its core utility is in automatically providing credentials to `pip`, `twine`, `uv`, or `pixi` without direct Python API calls by the user. Users typically do not import and use `keyrings.codeartifact` directly.
  Fix: Ensure `keyrings-codeartifact` is installed in the environment where your package manager (pip, twine, etc.) is run. Configure your package manager to point to the CodeArtifact repository URL.
• gotcha CodeArtifact authorization tokens are temporary and expire (defaulting to 12 hours). `keyrings.codeartifact` is designed to refresh these tokens automatically. If you encounter authentication failures, ensure your underlying AWS credentials (e.g., in `~/.aws/credentials`) are valid and have permissions to `codeartifact:GetAuthorizationToken`.
  Fix: Verify your AWS CLI configuration (`aws sts get-caller-identity`). If issues persist, running `keyring diagnose` can help identify problems with the keyring setup or location of the `keyringrc.cfg` file.
• gotcha When using `uv` or `pipx`, `keyring` and `keyrings.codeartifact` often need to be installed in the same environment (or globally if `uv` is configured for subprocess mode) for `keyring` to properly discover and utilize the CodeArtifact backend. Installing them in separate isolated environments might prevent `keyring` from functioning correctly.
  Fix: For `uv`, use `uv tool install keyring --with keyrings.codeartifact`. For `pipx`, use `pipx install keyring` and then `pipx inject keyring keyrings.codeartifact` to ensure they share the same virtual environment.
• gotcha Custom configuration options (e.g., `profile_name`, `token_duration`, explicit `aws_access_key_id`/`aws_secret_access_key`) for `keyrings.codeartifact` are managed via the `keyringrc.cfg` file. The location of this file can vary by platform. Incorrectly configured options can lead to authentication failures.
  Fix: Run `keyring diagnose` to find the exact location of `keyringrc.cfg` on your system. Refer to the `keyrings.codeartifact` documentation for available options and their correct syntax within the `[codeartifact]` section.
• gotcha On Windows, some users have reported issues with `keyring` backends (which `keyrings.codeartifact` utilizes) related to character limits for tokens stored in the credential manager. This can lead to authentication failures for very long tokens.
  Fix: If encountering issues specifically on Windows, consider setting `poetry config keyring.enabled false` if using Poetry, or exploring alternatives if a token character limit is suspected to be the root cause. This is a rare edge case, but worth noting.

Install

• pip install keyrings-codeartifact Install with pip

Imports

• keyrings.codeartifact

  import keyrings.codeartifact

  While `keyrings.codeartifact` is an importable module, its primary function is to register itself as a backend for the `keyring` library upon installation. Users typically do not directly import classes or functions from `keyrings.codeartifact` for its core credential-providing functionality; rather, `pip`, `twine`, `uv`, or `pixi` implicitly utilize it via the `keyring` abstraction.

Quickstart

This quickstart demonstrates how to set up `keyrings-codeartifact` for use with `pip`. The library integrates automatically once installed, provided your AWS CLI credentials are configured. Users interact with their package manager (`pip`, `twine`, `uv`, `pixi`) normally, and `keyrings.codeartifact` transparently supplies the necessary tokens.

# 1. Install the keyrings-codeartifact package
# pip install keyrings-codeartifact

# 2. Ensure your AWS CLI is configured with appropriate credentials.
#    For example, through ~/.aws/credentials or environment variables (AWS_ACCESS_KEY_ID, etc.).
#    You can verify with: aws sts get-caller-identity

# 3. Configure pip to use your AWS CodeArtifact repository.
#    Replace <DOMAIN>, <ACCOUNT_ID>, <REGION>, <REPOSITORY> with your CodeArtifact details.
#    The 'aws' username is required by CodeArtifact for token-based authentication.
CODEARTIFACT_INDEX_URL = "https://<DOMAIN>-<ACCOUNT_ID>.d.codeartifact.<REGION>.amazonaws.com/pypi/<REPOSITORY>/simple/"

# Example of how pip would implicitly use the keyring backend:
# Assuming 'my-private-package' is in your CodeArtifact repository
# and `keyrings-codeartifact` is installed and AWS credentials are set up.
# This command would use the credential provided by keyrings.codeartifact automatically.
# pip install my-private-package --index-url $CODEARTIFACT_INDEX_URL

# To demonstrate that it doesn't break standard pip operations, you can try installing a public package:
# pip install requests