> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# ft-circleci-orbs/cloudsmith-python

Install python packages from and publish python packages to Cloudsmith using short-lived OIDC credentials.
Note, all commands require the following environment variables to be set:
 - CLOUDSMITH_ORGANISATION : The identity/slug of the Cloudsmith organisation to use when authenticating with OIDC. Defaults to "financial-times" if not set.
 - CLOUDSMITH_SERVICE_ACCOUNT : The identity/slug of the Cloudsmith service account to use when authenticating with OIDC.
These are used to authenticate with Cloudsmith using OIDC and can be found in the Cloudsmith UI - https://cloudsmith.io/.


## Commands

### set_env_vars_for_pip

Generate temporary Cloudsmith credentials using OIDC and construct a pip index URL string for a specific Cloudsmith repository and service account. On completion the command sets the CLOUDSMITH_PIP_INDEX_URL environment variable for use with pip. The index url includes Cloudsmith authentication credentials generated using OIDC.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `repository` | string |  | The identity/slug of the Cloudsmith repository |

### set_env_vars_for_poetry

Generate temporary Cloudsmith credentials using OIDC and construct a poetry username and password from the service account credentials. On completion the command sets the CLOUDSMITH_POETRY_USERNAME and CLOUDSMITH_POETRY_PASSWORD environment variables for use with poetry.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `repository` | string |  | The identity/slug of the Cloudsmith repository |

### set_env_vars_for_twine

Generate temporary Cloudsmith credentials using OIDC and construct a repository URL for a specific Cloudsmith repository and service account. On completion the command sets the CLOUDSMITH_TWINE_REPOSITORY_URL, CLOUDSMITH_TWINE_USERNAME and CLOUDSMITH_TWINE_PASSWORD environment variables for use with twine.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `repository` | string |  | The identity/slug of the Cloudsmith repository |

### upload_package

Generate temporary Cloudsmith credentials using OIDC and upload a python package to a Cloudsmith repository using the Cloudsmith CLI.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `dist_dir` | string | dist | The distribution directory where package source distribution and wheel files are located |
| `repository` | string |  | The identity/slug of the Cloudsmith repository |

## Examples

### configure_pip_index_url

Configure pip and install requirements from Cloudsmith.


```yaml
version: '2.1'
orbs:
  cloudsmith-python: ft-circleci-orbs/cloudsmith-python@1.1
jobs:
  build:
    docker:
      - image: cimg/python:3.13
    steps:
      - checkout
      - run: python -m ensurepip --upgrade
      - cloudsmith-python/set_env_vars_for_pip:
          repository: your-repository-id
      - run: python -m pip config set global.index-url "$CLOUDSMITH_PIP_INDEX_URL"
      - run: python -m pip install -r requirements.txt
workflows:
  main:
    jobs:
      - build
```

### pip_install_package

Install a package from Cloudsmith using pip.


```yaml
version: '2.1'
orbs:
  cloudsmith-python: ft-circleci-orbs/cloudsmith-python@1.1
jobs:
  build:
    docker:
      - image: cimg/python:3.13
    steps:
      - checkout
      - run: python -m ensurepip --upgrade
      - cloudsmith-python/set_env_vars_for_pip:
          repository: your-repository-id
      - run: >-
          python -m pip install your-package==0.0.0 --index-url
          "$CLOUDSMITH_PIP_INDEX_URL"
workflows:
  main:
    jobs:
      - build
```

### pip_install_requirements

Install requirements from Cloudsmith using pip.


```yaml
version: '2.1'
orbs:
  cloudsmith-python: ft-circleci-orbs/cloudsmith-python@1.1
jobs:
  build:
    docker:
      - image: cimg/python:3.13
    steps:
      - checkout
      - run: python -m ensurepip --upgrade
      - cloudsmith-python/set_env_vars_for_pip:
          repository: your-repository-id
      - run: >-
          python -m pip install -r requirements.txt --index-url
          "$CLOUDSMITH_PIP_INDEX_URL"
workflows:
  main:
    jobs:
      - build
```

### pipenv_install_packages

Install a package from Cloudsmith using pipenv. The source URL in the Pipfile must reference $CLOUDSMITH_PIP_INDEX_URL. Note: Ensure the python_version in your Pipfile matches the Python version in your Docker image to avoid installation errors.


```yaml
version: '2.1'
orbs:
  cloudsmith-python: ft-circleci-orbs/cloudsmith-python@1.1
jobs:
  build:
    docker:
      - image: cimg/python:3.13
    steps:
      - checkout
      - run: python -m ensurepip --upgrade
      - cloudsmith-python/set_env_vars_for_pip:
          repository: your-repository-id
      - run: python -m pip install pipenv
      - run: pipenv install
workflows:
  main:
    jobs:
      - build
```

### poetry_install_packages

Install a package from Cloudsmith using poetry. The source URL in pyproject.toml must be set to https://packages.ft.com/basic/your-repository-id/python/simple/ and the corresponding cloudsmith-source-url parameter is an arbitrary label for the Cloudsmith Source URL. Note: Ensure the Python version requirement in your pyproject.toml matches the Python version in your Docker image.


```yaml
version: '2.1'
orbs:
  cloudsmith-python: ft-circleci-orbs/cloudsmith-python@1.1
jobs:
  build:
    docker:
      - image: cimg/python:3.13
    steps:
      - checkout
      - run: python -m ensurepip --upgrade
      - run: python -m pip install poetry --upgrade --user
      - cloudsmith-python/set_env_vars_for_poetry:
          repository: your-repository-id
      - run:
          command: |
            poetry config http-basic.cloudsmith-source-url \
            $CLOUDSMITH_POETRY_USERNAME $CLOUDSMITH_POETRY_PASSWORD
            poetry add -q simplepkg
            poetry install
          name: Install Poetry package
workflows:
  main:
    jobs:
      - build
```

### upload_package_using_cli

Upload a python package to Cloudsmith using the Cloudsmith CLI.


```yaml
version: '2.1'
orbs:
  cloudsmith-python: ft-circleci-orbs/cloudsmith-python@1.1
jobs:
  build:
    docker:
      - image: cimg/python:3.13
    steps:
      - checkout
      - run: python -m ensurepip --upgrade
      - run:
          command: |
            python -m pip install build --upgrade --user
            python -m build
          name: Build source and wheel distributions
      - cloudsmith-python/upload_package:
          repository: your-repository-id
workflows:
  main:
    jobs:
      - build
```

### upload_package_using_poetry

Upload a package from Cloudsmith using poetry. For uploads, the source URL in pyproject.toml must be set to https://python.cloudsmith.io/financial-times/your-repository-id/ and the corresponding parameter cloudsmith-source-url is an arbitrary label for the Cloudsmith Source URL.


```yaml
version: '2.1'
orbs:
  cloudsmith-python: ft-circleci-orbs/cloudsmith-python@1.1
jobs:
  build:
    docker:
      - image: cimg/python:3.13
    steps:
      - checkout
      - run: python -m ensurepip --upgrade
      - run: python -m pip install poetry --upgrade --user
      - cloudsmith-python/set_env_vars_for_poetry:
          repository: your-repository-id
      - run:
          command: |
            poetry config http-basic.cloudsmith-source-url \
            $CLOUDSMITH_POETRY_USERNAME $CLOUDSMITH_POETRY_PASSWORD
            poetry build
            poetry publish -r cloudsmith-source-url
          name: Create Poetry package and publish package
workflows:
  main:
    jobs:
      - build
```

### upload_package_using_twine

Upload a python package to Cloudsmith using twine.


```yaml
version: '2.1'
orbs:
  cloudsmith-python: ft-circleci-orbs/cloudsmith-python@1.1
jobs:
  build:
    docker:
      - image: cimg/python:3.13
    steps:
      - checkout
      - run: python -m ensurepip --upgrade
      - run:
          command: |
            python -m pip install build --upgrade --user
            python -m build
          name: Build source and wheel distributions
      - run: python -m pip install twine --upgrade --user
      - cloudsmith-python/set_env_vars_for_twine:
          repository: your-repository-id
      - run:
          command: |
            twine upload \
                --username $CLOUDSMITH_TWINE_USERNAME \
                --password $CLOUDSMITH_TWINE_PASSWORD \
                --repository-url $CLOUDSMITH_TWINE_REPOSITORY_URL \
                dist/*
          name: Publish source and wheel distributions to Cloudsmith
workflows:
  main:
    jobs:
      - build
```