diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-06 03:09:14 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-06 03:09:14 +0300 |
commit | c93374099a04d318af464f5b3a54a8aafdbca81f (patch) | |
tree | 9e4296521eb85a95a90d058982c30b922836eaa7 /doc/user/packages/pypi_repository | |
parent | 1bc5af76617026dec53016cb0881ec834ccab807 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/user/packages/pypi_repository')
-rw-r--r-- | doc/user/packages/pypi_repository/index.md | 163 |
1 files changed, 79 insertions, 84 deletions
diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 33c37ee6a6c..7df0f5ef1ce 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -4,42 +4,28 @@ group: Package info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers --- -# GitLab PyPI Repository +# PyPI packages in the Package Registry > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208747) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.10. > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3. -With the GitLab PyPI Repository, every project can have its own space to store PyPI packages. +Publish PyPI packages in your project’s Package Registry. Then install the +packages whenever you need to use them as a dependency. The GitLab PyPI Repository works with: - [pip](https://pypi.org/project/pip/) - [twine](https://pypi.org/project/twine/) -## Setting up your development environment +## Build a PyPI package -You need a recent version of [pip](https://pypi.org/project/pip/) and [twine](https://pypi.org/project/twine/). - -## Enabling the PyPI Repository - -NOTE: **Note:** -This option is available only if your GitLab administrator has -[enabled support for the Package Registry](../../../administration/packages/index.md). - -After the PyPI Repository is enabled, it is available for all new projects -by default. To enable it for existing projects, or if you want to disable it: - -1. Navigate to your project's **Settings > General > Visibility, project features, permissions**. -1. Find the Packages feature and enable or disable it. -1. Click on **Save changes** for the changes to take effect. - -You should then be able to see the **Packages & Registries** section on the left sidebar. +This section covers creating a new example PyPI package to upload. This is a +quickstart to test out the **GitLab PyPI Registry**. If you already understand +how to build and publish your own packages, move on to the [next section](#authenticate-with-the-package-registry). -## Getting started +### Install pip and twine -This section covers creating a new example PyPI package to upload. This is a -quickstart to test out the **GitLab PyPI Registry**. If you already understand how -to build and publish your own packages, move on to the [next section](#adding-the-gitlab-pypi-repository-as-a-source). +You need a recent version of [pip](https://pypi.org/project/pip/) and [twine](https://pypi.org/project/twine/). ### Create a project @@ -97,8 +83,8 @@ Type "help", "copyright", "credits" or "license" for more information. Hello from MyPyPiPackage ``` -Once we've verified that the sample project is working as above, we can next -work on creating a package. +After we've verified that the sample project is working as previously described, +we can next work on creating a package. ### Create a package @@ -111,13 +97,13 @@ touch setup.py This file contains all the information about our package. For more information about this file, see [creating setup.py](https://packaging.python.org/tutorials/packaging-projects/#creating-setup-py). -GitLab identifies packages based on +Becaue GitLab identifies packages based on [Python normalized names (PEP-503)](https://www.python.org/dev/peps/pep-0503/#normalized-names), -so ensure your package name meets these requirements. -See the [installation section](#install-packages) for more details. +ensure your package name meets these requirements. See the [installation section](#publish-a-pypi-package-by-using-cicd) +for more details. -For this guide, we don't need to extensively fill out this file, simply add the -below to your `setup.py`: +For this guide, we don't need to extensively fill out this file. Add the +following to your `setup.py`: ```python import setuptools @@ -138,7 +124,7 @@ setuptools.setup( ) ``` -Save the file, then execute the setup like so: +Save the file, and then execute the setup: ```shell python3 setup.py sdist bdist_wheel @@ -157,18 +143,21 @@ And confirm your output matches the below: mypypipackage-0.0.1-py3-none-any.whl mypypipackage-0.0.1.tar.gz ``` -Our package is now all set up and ready to be uploaded to the **GitLab PyPI -Package Registry**. Before we do so, we next need to set up authentication. +The package is now all set up and is ready to be uploaded to the +_GitLab PyPI Package Registry_. Before we do so, we next need to set up +authentication. -## Adding the GitLab PyPI Repository as a source +## Authenticate with the Package Registry -### Authenticating with a personal access token +### Authenticate with a personal access token You need the following: -- A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. +- A personal access token. You can generate a + [personal access token](../../../user/profile/personal_access_tokens.md) + with the scope set to `api` for repository authentication. - A suitable name for your source. -- Your project ID which can be found on the home page of your project. +- Your project ID, which is found on the home page of your project. Edit your `~/.pypirc` file and add the following: @@ -183,13 +172,15 @@ username = __token__ password = <your personal access token> ``` -### Authenticating with a deploy token +### Authenticate with a deploy token You need the following: -- A deploy token. You can generate a [deploy token](./../../project/deploy_tokens/index.md) with the `read_package_registry` and/or `write_package_registry` scopes for repository authentication. +- A deploy token. You can generate a [deploy token](./../../project/deploy_tokens/index.md) + with the `read_package_registry` or `write_package_registry` scopes for + repository authentication. - A suitable name for your source. -- Your project ID which can be found on the home page of your project. +- Your project ID, which is found on the home page of your project. Edit your `~/.pypirc` file and add the following: @@ -204,16 +195,18 @@ username = <deploy token username> password = <deploy token> ``` -## Uploading packages +## Publish a PyPI package -When uploading packages, note that: +When publishing packages, note that: - The maximum allowed size is 50 Megabytes. -- You cannot upload the same version of a package multiple times. If you try, you receive the error `Validation failed: File name has already been taken`. +- You can't upload the same version of a package multiple times. If you try, + you'll receive the error `Validation failed: File name has already been taken`. ### Ensure your version string is valid -If your version string (for example, `0.0.1`) is invalid, it will be rejected. GitLab uses the following regex to validate the version string. +If your version string (for example, `0.0.1`) is invalid, it will be rejected. +GitLab uses the following regex to validate the version string. ```ruby \A(?: @@ -227,13 +220,14 @@ If your version string (for example, `0.0.1`) is invalid, it will be rejected. G )\z}xi ``` -You can play around with the regex and try your version strings on [this regular expression editor](https://rubular.com/r/FKM6d07ouoDaFV). +You can experiment with the regex and try your version strings using this +[regular expression editor](https://rubular.com/r/FKM6d07ouoDaFV). -For more details about the regex used, please check the [documentation here](https://www.python.org/dev/peps/pep-0440/#appendix-b-parsing-version-strings-with-regular-expressions)) +For more details about the regex used, review this [documentation](https://www.python.org/dev/peps/pep-0440/#appendix-b-parsing-version-strings-with-regular-expressions). -### Upload packages with Twine +### Publish a PyPI package by using twine -If you were following the guide above, then the `MyPyPiPackage` package should +If you were following the steps on this page, the `MyPyPiPackage` package should be ready to be uploaded. Run the following command: ```shell @@ -260,8 +254,8 @@ you can upload to the repository with the authentication inline: TWINE_PASSWORD=<personal_access_token or deploy_token> TWINE_USERNAME=<username or deploy_token_username> python3 -m twine upload --repository-url https://gitlab.com/api/v4/projects/<project_id>/packages/pypi dist/* ``` -If you did not follow the guide above, then you need to ensure your package -has been properly built and you [created a PyPI package with `setuptools`](https://packaging.python.org/tutorials/packaging-projects/). +If you didn't use the steps on this page, you need to ensure your package has +been properly built, and that you [created a PyPI package with `setuptools`](https://packaging.python.org/tutorials/packaging-projects/). You can then upload your package using the following command: @@ -272,9 +266,42 @@ python -m twine upload --repository <source_name> dist/<package_file> Where: - `<package_file>` is your package filename, ending in `.tar.gz` or `.whl`. -- `<source_name>` is the [source name used during setup](#adding-the-gitlab-pypi-repository-as-a-source). +- `<source_name>` is the [source name used during setup](#authenticate-with-the-package-registry). + +### Publish a PyPI package by using CI/CD + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202012) in GitLab 13.4. + +To work with PyPI commands within [GitLab CI/CD](./../../../ci/README.md), you +can use `CI_JOB_TOKEN` in place of the personal access token or deploy a token +in your commands. + +For example: + +```yaml +image: python:latest -## Install packages +run: + script: + - pip install twine + - python setup.py sdist bdist_wheel + - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/pypi dist/* +``` + +You can also use `CI_JOB_TOKEN` in a `~/.pypirc` file that you check into GitLab: + +```ini +[distutils] +index-servers = + gitlab + +[gitlab] +repository = https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/pypi +username = gitlab-ci-token +password = ${env.CI_JOB_TOKEN} +``` + +## Install a PyPI package Install the latest version of a package using the following command: @@ -310,35 +337,3 @@ GitLab looks for packages using so the characters `-`, `_`, and `.` are all treated the same and repeated characters are removed. A `pip install` request for `my.package` looks for packages that match any of the three characters, such as `my-package`, `my_package`, and `my....package`. - -## Using GitLab CI with PyPI packages - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202012) in GitLab 13.4. - -To work with PyPI commands within [GitLab CI/CD](./../../../ci/README.md), you can use -`CI_JOB_TOKEN` in place of the personal access token or deploy token in your commands. - -For example: - -```yaml -image: python:latest - -run: - script: - - pip install twine - - python setup.py sdist bdist_wheel - - TWINE_PASSWORD=${CI_JOB_TOKEN} TWINE_USERNAME=gitlab-ci-token python -m twine upload --repository-url https://gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/pypi dist/* -``` - -You can also use `CI_JOB_TOKEN` in a `~/.pypirc` file that you check into GitLab: - -```ini -[distutils] -index-servers = - gitlab - -[gitlab] -repository = https://gitlab.com/api/v4/projects/${env.CI_PROJECT_ID}/packages/pypi -username = gitlab-ci-token -password = ${env.CI_JOB_TOKEN} -``` |