Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md).

# Using Python
<a name="packages-python"></a>

These topics describe how to use `pip`, the Python package manager, and `twine`, the Python package publishing utility, with CodeCatalyst.

**Topics**
+ [Configuring pip and installing Python packages](packages-python-pip.md)
+ [Configuring Twine and publishing Python packages](packages-python-twine.md)
+ [Python package name normalization](python-name-normalization.md)
+ [Python compatibility](packages-python-compatibility.md)

# Configuring pip and installing Python packages
<a name="packages-python-pip"></a>

To use `pip` with CodeCatalyst, you must connect `pip` to your package repository and provide a personal access token for authentication. You can view instructions for connecting `pip` to your package repository in the CodeCatalyst console. After you authenticate and connect `pip` to CodeCatalyst, you can run `pip` commands.

**Contents**
+ [Installing Python packages from CodeCatalyst with pip](#pip-install)
+ [Consuming Python packages from PyPI through CodeCatalyst](#pip-install-pypi)
+ [pip command support](#pip-command-support)
  + [Supported commands that interact with a repository](#supported-pip-commands-that-interact-with-a-repository)
  + [Supported client-side commands](#supported-pip-client-side-commands)

## Installing Python packages from CodeCatalyst with pip
<a name="pip-install"></a>

The following instructions explain how to configure `pip` to install Python packages from your CodeCatalyst package repository or one of its upstream repositories.

**To configure and use `pip` to install Python packages from your CodeCatalyst package repository**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. On the overview page for your project, choose **Packages**.

1. Choose your package repository from the list of package repositories.

1. Choose **Connect to repository**.

1. In the **Connect to repository** dialog box, choose **pip** from the list of package manager clients.

1. You will need a personal access token (PAT) to authenticate pip with CodeCatalyst. If you already have one, you can use that. If not, you can create one here.

   1. Choose **Create token**.

   1. Choose **Copy** to copy your PAT.
**Warning**  
You will not be able to see or copy your PAT again after you close the dialog box.

1. Use the `pip config` command to set the CodeCatalyst registry URL and credentials. Replace the following values.
**Note**  
If copying from the console instructions, the following values should be updated for you and should not be changed.
   + Replace *username* with your CodeCatalyst user name.
   + Replace *PAT* with your CodeCatalyst PAT.
   + Replace *space\$1name* with your CodeCatalyst space name.
   + Replace *proj\$1name* with your CodeCatalyst project name.
   + Replace *repo\$1name* with your CodeCatalyst package repository name.

   ```
   pip config set global.index-url https://username:PAT@https://packages.region.codecatalyst.aws/pypi/space_name/proj_name/repo_name/simple/
   ```

1. Assuming that a package is present in your repository or one of its upstream repositories, you can install it with `pip install`. For example, use the following command to install the `requests` package.

   ```
   pip install requests
   ```

   Use the `-i` option to revert temporarily to installing packages from [https://pypi.org](https://pypi.org) instead of your CodeCatalyst package repository.

   ```
   pip install -i https://pypi.org/simple requests
   ```

## Consuming Python packages from PyPI through CodeCatalyst
<a name="pip-install-pypi"></a>

You can consume Python packages from the [Python Package Index (PyPI)](https://www.pypi.org/) through a CodeCatalyst repository by configuring the repository with an upstream connection to **PyPI**. Packages consumed from **PyPI** are ingested and stored in your CodeCatalyst repository.

**To consume packages from PyPI**

1. If you haven't already, configure pip with your CodeCatalyst package repository by following the steps in [Installing Python packages from CodeCatalyst with pip](#pip-install). 

1. Ensure that your repository has added **PyPI** as an upstream source. You can check which upstream sources are added or add **PyPI** as an upstream source by following the instructions in [Adding an upstream repository](packages-upstream-repositories-add.md) and choosing the **PyPI store** repository.

For more information about requesting packages from upstream repositories, see [Requesting a package version with upstream repositories](packages-upstream-repositories-request.md).

## pip command support
<a name="pip-command-support"></a>

The following sections summarize the pip commands that are supported, by CodeCatalyst repositories, in addition to specific commands that are not supported.

**Topics**
+ [Supported commands that interact with a repository](#supported-pip-commands-that-interact-with-a-repository)
+ [Supported client-side commands](#supported-pip-client-side-commands)

### Supported commands that interact with a repository
<a name="supported-pip-commands-that-interact-with-a-repository"></a>

This section lists `pip` commands where the `pip` client makes one or more requests to the registry it's been configured with. These commands have been verified to function correctly when invoked against a CodeCatalyst package repository.


****  

| Command | Description | 
| --- | --- | 
|   [install](https://pip.pypa.io/en/stable/reference/pip_install/)   |  Install packages.  | 
|   [download](https://pip.pypa.io/en/stable/reference/pip_download/)   |  Download packages.  | 

CodeCatalyst does not implement `pip search`. If you have configured `pip` with a CodeCatalyst package repository, running `pip search` will search and show packages from [PyPI](https://pypi.org/).

### Supported client-side commands
<a name="supported-pip-client-side-commands"></a>

These commands don't require any direct interaction with a repository, so CodeCatalyst does not need to do anything to support them.


****  

| Command | Description | 
| --- | --- | 
|   [uninstall](https://pip.pypa.io/en/stable/reference/pip_uninstall/)   |  Uninstall packages.  | 
|   [freeze](https://pip.pypa.io/en/stable/reference/pip_freeze/)   |  Output installed packages in requirements format.  | 
|   [list](https://pip.pypa.io/en/stable/reference/pip_list/)   |  List installed packages.  | 
|   [show](https://pip.pypa.io/en/stable/reference/pip_show/)   |  Show information about installed packages.  | 
|   [check](https://pip.pypa.io/en/stable/reference/pip_check/)   |  Verify that installed packages have compatible dependencies.  | 
|   [config](https://pip.pypa.io/en/stable/reference/pip_config/)   |  Manage local and global configuration.  | 
|   [wheel](https://pip.pypa.io/en/stable/reference/pip_wheel/)   |  Build wheels from your requirements.  | 
|   [hash](https://pip.pypa.io/en/stable/reference/pip_hash/)   |  Compute hashes of package archives.  | 
|   [completion](https://pip.pypa.io/en/stable/user_guide/#command-completion)   |  Helps with command completion.  | 
|   [debug](https://pip.pypa.io/en/stable/reference/pip_debug/)   |  Show information useful for debugging.  | 
|  help  |  Show help for commands.  | 

# Configuring Twine and publishing Python packages
<a name="packages-python-twine"></a>

To use `twine` with CodeCatalyst, you must connect `twine` to your package repository and provide a personal access token for authentication. You can view instructions for connecting `twine` to your package repository in the CodeCatalyst console. After you authenticate and connect `twine` to CodeCatalyst, you can run `twine` commands.

## Publishing packages to CodeCatalyst with Twine
<a name="packages-twine-publish"></a>

The following instructions explain how to authenticate and connect `twine` to your CodeCatalyst package repository.

**To configure and use `twine` to publish packages to your CodeCatalyst package repository**

1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).

1. On the overview page for your project, choose **Packages**.

1. Choose your package repository from the list of package repositories.

1. Choose **Connect to repository**.

1. In the **Connect to repository** dialog box, choose **Twine** from the list of package manager clients.

1. You will need a personal access token (PAT) to authenticate twine with CodeCatalyst. If you already have one, you can use that. If not, you can create one here.

   1. Choose **Create token**.

   1. Choose **Copy** to copy your PAT.
**Warning**  
You will not be able to see or copy your PAT again after you close the dialog box.

1. You can configure twine with a `.pypirc` file, or with environment variables.

   1. **To configure with a `.pypirc` file.**

      Open `~/.pypirc` in your editor of choice.

      Add an index server for CodeCatalyst, including the repository, user name, and PAT that you created and copied in a previous step. Replace the following values.
**Note**  
If copying from the console instructions, the following values should be updated for you and should not be changed.
      + Replace *username* with your CodeCatalyst user name.
      + Replace *PAT* with your CodeCatalyst PAT.
      + Replace *space\$1name* with your CodeCatalyst space name.
      + Replace *proj\$1name* with your CodeCatalyst project name.
      + Replace *repo\$1name* with your CodeCatalyst package repository name.

      ```
      [distutils]
      index-servers = proj-name/repo-name
      
      [proj-name/repo-name]
      repository = https://packages.region.codecatalyst.aws/pypi/space_name/proj_name/repo_name/
      password = PAT
      username = username
      ```

   1. **To configure with environment variables.**

      Set the following environment variables. In the `TWINE_REPOSITORY_URL` value, update *space\$1name*, *proj\$1name*, and *repo\$1name* with your CodeCatalyst space, project, and package repository names.

      ```
      export TWINE_USERNAME=username
      ```

      ```
      export TWINE_PASSWORD=PAT
      ```

      ```
      export TWINE_REPOSITORY_URL="https://packages.region.codecatalyst.aws/pypi/space_name/proj_name/repo_name/"
      ```

1. Publish a Python distribution with the `twine upload` command.

# Python package name normalization
<a name="python-name-normalization"></a>

CodeCatalyst normalizes package names before storing them, which means the package names in CodeCatalyst may be different than the name provided when the package was published.

For Python packages, when performing normalization the package name is lowercased and all instances of the characters `.`, `-`, and `_` are replaced with a single `-` character. So the package names `pigeon_cli` and `pigeon.cli` are normalized and stored as `pigeon-cli`. The non-normalized name can be used by pip and twine. For more information about Python package name normalization, see [PEP 503](https://www.python.org/dev/peps/pep-0503/#normalized-names) in the Python documentation.

# Python compatibility
<a name="packages-python-compatibility"></a>

 While CodeCatalyst does not support the `/simple/` API, it does support the `Legacy` API operations. CodeCatalyst does not support PyPI's `XML-RPC` or `JSON` API operations. 

For more information, see the following on the Python Packaging Authority's GitHub repository.
+ [Legacy API](https://warehouse.pypa.io/api-reference/legacy.html)
+ [XML-RPC API](https://github.com/pypi/warehouse/blob/main/docs/dev/api-reference/xml-rpc.rst)
+ [JSON API](https://docs.pypi.org/api/json/)