From bbbeb2d07d4f7fd0191032c219b40565fd83454f Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 29 Apr 2024 06:26:28 +0200 Subject: Adding upstream version 3.8.0. Signed-off-by: Daniel Baumann --- doc/upload.rst | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 doc/upload.rst (limited to 'doc/upload.rst') diff --git a/doc/upload.rst b/doc/upload.rst new file mode 100644 index 0000000..df5af5e --- /dev/null +++ b/doc/upload.rst @@ -0,0 +1,77 @@ +Controlling package uploads +=========================== + +.. program:: flit publish + +The command ``flit publish`` will upload your package to a package index server. +The default settings let you upload to `PyPI `_, +the default Python Package Index, with a single user account. + +If you want to upload to other servers, or with more than one user account, +or upload packages from a continuous integration job, +you can configure Flit in two main ways: + +Using .pypirc +------------- + +You can create or edit a config file in your home directory, ``~/.pypirc`` that +will be used by default or you can specify a custom location. +This is also used by other Python tools such as `twine +`_. + +For instance, to upload a package to the `Test PyPI server `_ +instead of the normal PyPI, use a config file looking like this: + +.. code-block:: ini + + [distutils] + index-servers = + pypi + testpypi + + [pypi] + repository = https://upload.pypi.org/legacy/ + username = sirrobin # Replace with your PyPI username + + [testpypi] + repository = https://test.pypi.org/legacy/ + username = sirrobin # Replace with your TestPyPI username + +You can select an index server from this config file with the +:option:`--repository` option:: + + flit publish --repository testpypi + +If you don't use this option, +Flit will use the server called ``pypi`` in the config file. If that doesn't +exist, it uploads to PyPI at ``https://upload.pypi.org/legacy/`` by default. + +If you publish a package and you don't have a ``.pypirc`` file, Flit will create +it to store your username. + +Flit tries to store your password securely using the +`keyring `_ library. +If keyring is not installed, Flit will ask for your password for each upload. +Alternatively, you can also manually add your password to the ``.pypirc`` file +(``password = ...``) + +.. _upload_envvars: + +Using environment variables +--------------------------- + +You can specify a server to upload to with :envvar:`FLIT_INDEX_URL`, and +pass credentials with :envvar:`FLIT_USERNAME` and :envvar:`FLIT_PASSWORD`. +Environment variables take precedence over the config file, except if you use +the :option:`--repository` option to explicitly pick a server from the config file. + +This can make it easier to automate uploads, for example to release packages +from a continuous integration job. + +.. warning:: + + Storing a password in an environment variable is convenient, but it's + `easy to accidentally leak it `_. + Look out for scripts that helpfully print all environment variables for + debugging, and remember that other scripts and libraries you run in + that environment have access to your password. -- cgit v1.2.3