diff --git a/doc/user/packages/pypi_repository/index.md b/doc/user/packages/pypi_repository/index.md index 11d7b8288133ce81bc9e2b246bfa5ade4b5cedd3..2be47534ac682a330f14cc9a2d7f513ba4532b59 100644 --- a/doc/user/packages/pypi_repository/index.md +++ b/doc/user/packages/pypi_repository/index.md @@ -28,6 +28,126 @@ by default. To enable it for existing projects, or if you want to disable it: You should then be able to see the **Packages** section on the left sidebar. +## Getting started + +This section will cover 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). + +### Create a project + +Understanding how to create a full Python project is outside the scope of this +guide, but you can create a small package to test out the registry. Start by +creating a new directory called `MyPyPiPackage`: + +```shell +mkdir MyPyPiPackage && cd MyPyPiPackage +``` + +After creating this, create another directory inside: + +```shell +mkdir mypypipackage && cd mypypipackage +``` + +Create two new files inside this directory to set up the basic project: + +```shell +touch __init__.py +touch greet.py +``` + +Inside `greet.py`, add the following code: + +```python +def SayHello(): + print("Hello from MyPyPiPackage") + return +``` + +Inside the `__init__.py` file, add the following: + +```python +from .greet import SayHello +``` + +Now that the basics of our project is completed, we can test that the code runs. +Start the Python prompt inside your top `MyPyPiPackage` directory. Then run: + +```python +>>> from mypypipackage import SayHello +>>> SayHello() +``` + +You should see an output similar to the following: + +```plaintext +Python 3.8.2 (v3.8.2:7b3ab5921f, Feb 24 2020, 17:52:18) +[Clang 6.0 (clang-600.0.57)] on darwin +Type "help", "copyright", "credits" or "license" for more information. +>>> from mypypipackage import SayHello +>>> SayHello() +Hello from MyPyPiPackage +``` + +Once we've verified that the sample project is working as above, we can next +work on creating a package. + +### Create a package + +Inside your `MyPyPiPackage` directory, we need to create a `setup.py` file. Run +the following: + +```shell +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). +For this guide, we don't need to extensively fill out this file, simply add the +below to your `setup.py`: + +```python +import setuptools + +setuptools.setup( + name="mypypipackage", + version="0.0.1", + author="Example Author", + author_email="author@example.com", + description="A small example package", + packages=setuptools.find_packages(), + classifiers=[ + "Programming Language :: Python :: 3", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", + ], + python_requires='>=3.6', +) +``` + +Save the file, then execute the setup like so: + +```shell +python3 setup.py sdist bdist_wheel +``` + +If successful, you should be able to see the output in a newly created `dist` +folder. Run: + +```shell +ls dist +``` + +And confirm your output matches the below: + +```plaintext +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. + ## Adding the GitLab PyPi Repository as a source You will need the following: @@ -39,6 +159,10 @@ You will need the following: Edit your `~/.pypirc` file and add the following: ```ini +[distutils] +index-servers = + gitlab + [gitlab] repository = https://gitlab.com/api/v4/projects/<project_id>/packages/pypi username = __token__ @@ -57,8 +181,30 @@ When uploading packages, note that: ### Upload packages with Twine -This section assumes that your project is properly built and you already [created a PyPi package with setuptools](https://packaging.python.org/tutorials/packaging-projects/). -Upload your package using the following command: +If you were following the guide above, then the `MyPyPiPackage` package should +be ready to be uploaded. Run the following command: + +```shell +python3 -m twine upload --repository gitlab dist/* +``` + +If successful, you should see the following: + +```plaintext +Uploading distributions to https://gitlab.com/api/v4/projects/<your_project_id>/packages/pypi +Uploading mypypipackage-0.0.1-py3-none-any.whl +100%|███████████████████████████████████████████████████████████████████████████████████████████| 4.58k/4.58k [00:00<00:00, 10.9kB/s] +Uploading mypypipackage-0.0.1.tar.gz +100%|███████████████████████████████████████████████████████████████████████████████████████████| 4.24k/4.24k [00:00<00:00, 11.0kB/s] +``` + +This indicates that the package was uploaded successfully. You can then navigate +to your project's **Packages** page and see the uploaded packages. + +If you did not follow the guide above, the you'll need to ensure your package +has been properly built and you [created a PyPi package with setuptools](https://packaging.python.org/tutorials/packaging-projects/). + +You can then upload your package using the following command: ```shell python -m twine upload --repository <source_name> dist/<package_file> @@ -82,3 +228,20 @@ Where: - `<package_name>` is the package name. - `<personal_access_token>` is your personal access token. - `<project_id>` is your project id number. + +If you were following the guide above and want to test installing the +`MyPyPiPackage` package, you can run the following: + +```shell +pip install mypypipackage --no-deps --index-url https://__token__:<personal_access_token>@gitlab.com/api/v4/projects/<your_project_id>/packages/pypi/simple +``` + +This should result in the following: + +```plaintext +Looking in indexes: https://__token__:****@gitlab.com/api/v4/projects/<your_project_id>/packages/pypi/simple +Collecting mypypipackage + Downloading https://gitlab.com/api/v4/projects/<your_project_id>/packages/pypi/files/d53334205552a355fee8ca35a164512ef7334f33d309e60240d57073ee4386e6/mypypipackage-0.0.1-py3-none-any.whl (1.6 kB) +Installing collected packages: mypypipackage +Successfully installed mypypipackage-0.0.1 +```