From 754b0f40d7a07502bde12dda4993cbd7d477cb3e Mon Sep 17 00:00:00 2001 From: Dmitrii O Date: Tue, 7 Mar 2023 16:45:13 +0100 Subject: [PATCH] chore: add help output for `run` and `update` to README (#478) --- README.rst | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/README.rst b/README.rst index 9192a68..72b1b07 100644 --- a/README.rst +++ b/README.rst @@ -124,6 +124,110 @@ not officially supported, and will not receive bugfixes or new features. Visit https://github.com/pypiserver/pypiserver for more information +More details about ``pypi-server run`` +-------------------------------------- + +Enter ``pypi-server run -h`` in the cmd-line to print a detailed usage +message *about starting the server*:: + + usage: pypi-server run [-h] [-v] [--log-file FILE] [--log-stream STREAM] [--log-frmt FORMAT] [--hash-algo HASH_ALGO] + [--backend {auto,simple-dir,cached-dir}] [--version] [-p PORT] [-i HOST] [-a AUTHENTICATE] [-P PASSWORD_FILE] [--disable-fallback] + [--fallback-url FALLBACK_URL] [--server METHOD] [-o] [--welcome HTML_FILE] [--cache-control AGE] [--log-req-frmt FORMAT] + [--log-res-frmt FORMAT] [--log-err-frmt FORMAT] + [package_directory [package_directory ...]] + + positional arguments: + package_directory The directory from which to serve packages. + + optional arguments: + -h, --help show this help message and exit + -v, --verbose Enable verbose logging; repeat for more verbosity. + --log-file FILE Write logging info into this FILE, as well as to stdout or stderr, if configured. + --log-stream STREAM Log messages to the specified STREAM. Valid values are stdout, stderr, and none + --log-frmt FORMAT The logging format-string. (see `logging.LogRecord` class from standard python library) + --hash-algo HASH_ALGO + Any `hashlib` available algorithm to use for generating fragments on package links. Can be disabled with one of (0, no, off, + false). + --backend {auto,simple-dir,cached-dir} + A backend implementation. Keep the default 'auto' to automatically determine whether to activate caching or not + --version show program's version number and exit + -p PORT, --port PORT Listen on port PORT (default: 8080) + -i HOST, -H HOST, --interface HOST, --host HOST + Listen on interface INTERFACE (default: 0.0.0.0) + -a AUTHENTICATE, --authenticate AUTHENTICATE + Comma-separated list of (case-insensitive) actions to authenticate (options: download, list, update; default: update). + + Any actions not specified are not authenticated, so to authenticate downloads and updates, but allow unauthenticated viewing of + the package list, you would use: + + pypi-server -a 'download, update' -P ./my_passwords.htaccess + + To disable authentication, use: + + pypi-server -a . -P . + + See the `-P` option for configuring users and passwords. + + Note that when uploads are not protected, the `register` command is not necessary, but `~/.pypirc` still needs username and + password fields, even if bogus. + -P PASSWORD_FILE, --passwords PASSWORD_FILE + Use an apache htpasswd file PASSWORD_FILE to set usernames and passwords for authentication. + + To allow unauthorized access, use: + + pypi-server -a . -P . + + --disable-fallback Disable the default redirect to PyPI for packages not found in the local index. + --fallback-url FALLBACK_URL + Redirect to FALLBACK_URL for packages not found in the local index. + --server METHOD Use METHOD to run the server. Valid values include paste, cherrypy, twisted, gunicorn, gevent, wsgiref, and auto. The default is to + use "auto", which chooses one of paste, cherrypy, twisted, or wsgiref. + -o, --overwrite Allow overwriting existing package files during upload. + --welcome HTML_FILE Use the contents of HTML_FILE as a custom welcome message on the home page. + --cache-control AGE Add "Cache-Control: max-age=AGE" header to package downloads. Pip 6+ requires this for caching. + --log-req-frmt FORMAT + A format-string selecting Http-Request properties to log; set to '%s' to see them all. + --log-res-frmt FORMAT + A format-string selecting Http-Response properties to log; set to '%s' to see them all. + --log-err-frmt FORMAT + A format-string selecting Http-Error properties to log; set to '%s' to see them all. + +More details about ``pypi-server update`` +----------------------------------------- + +Enter ``pypi-server update -h`` in the cmd-line to print a detailed usage +message *about updating the managed packages*:: + + usage: pypi-server update [-h] [-v] [--log-file FILE] [--log-stream STREAM] [--log-frmt FORMAT] [--hash-algo HASH_ALGO] + [--backend {auto,simple-dir,cached-dir}] [--version] [-x] [-d DOWNLOAD_DIRECTORY] [-u] [--blacklist-file IGNORELIST_FILE] + [package_directory [package_directory ...]] + + positional arguments: + package_directory The directory from which to serve packages. + + optional arguments: + -h, --help show this help message and exit + -v, --verbose Enable verbose logging; repeat for more verbosity. + --log-file FILE Write logging info into this FILE, as well as to stdout or stderr, if configured. + --log-stream STREAM Log messages to the specified STREAM. Valid values are stdout, stderr, and none + --log-frmt FORMAT The logging format-string. (see `logging.LogRecord` class from standard python library) + --hash-algo HASH_ALGO + Any `hashlib` available algorithm to use for generating fragments on package links. Can be disabled with one of (0, no, off, + false). + --backend {auto,simple-dir,cached-dir} + A backend implementation. Keep the default 'auto' to automatically determine whether to activate caching or not + --version show program's version number and exit + -x, --execute Execute the pip commands rather than printing to stdout + -d DOWNLOAD_DIRECTORY, --download-directory DOWNLOAD_DIRECTORY + Specify a directory where packages updates will be downloaded. The default behavior is to use the directory which contains the + package being updated. + -u, --allow-unstable Allow updating to unstable versions (alpha, beta, rc, dev, etc.) + --blacklist-file IGNORELIST_FILE, --ignorelist-file IGNORELIST_FILE + Don't update packages listed in this file (one package name per line, without versions, '#' comments honored). This can be useful + if you upload private packages into pypiserver, but also keep a mirror of public packages that you regularly update. Attempting to + pull an update of a private package from `pypi.org` might pose a security risk - e.g. a malicious user might publish a higher + version of the private package, containing arbitrary code. + Client-Side Configurations ==========================