summaryrefslogtreecommitdiffstats
path: root/doc/upload.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-29 04:26:28 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-29 04:26:28 +0000
commitbbbeb2d07d4f7fd0191032c219b40565fd83454f (patch)
tree3c08f1e09ed89a004867762ab40f3b610f6c0fa1 /doc/upload.rst
parentInitial commit. (diff)
downloadflit-bbbeb2d07d4f7fd0191032c219b40565fd83454f.tar.xz
flit-bbbeb2d07d4f7fd0191032c219b40565fd83454f.zip
Adding upstream version 3.8.0.upstream/3.8.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/upload.rst')
-rw-r--r--doc/upload.rst77
1 files changed, 77 insertions, 0 deletions
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 <https://pypi.org/>`_,
+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
+<https://pypi.python.org/pypi/twine>`_.
+
+For instance, to upload a package to the `Test PyPI server <https://test.pypi.org/>`_
+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 <https://pypi.python.org/pypi/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 <https://www.diogomonica.com/2017/03/27/why-you-shouldnt-use-env-variables-for-secret-data/>`_.
+ 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.