From 73c8cb704f5d0c6715bbc60729ccc59e701d0a49 Mon Sep 17 00:00:00 2001 From: Kostis Anagnostopoulos Date: Sat, 25 Jun 2016 04:02:59 +0200 Subject: [PATCH] doc: promote API as new top-level section & reoder it. --- README.rst | 112 +++++++++++++++++++++++------------------ pypiserver/__init__.py | 1 + 2 files changed, 65 insertions(+), 48 deletions(-) diff --git a/README.rst b/README.rst index dc2db1f..aa2734f 100644 --- a/README.rst +++ b/README.rst @@ -502,63 +502,44 @@ management. An example configuration file for ``supervisor`` is given below:: From there, the process can be managed via ``supervisord`` using ``supervisorctl``. -Running via the API -------------------- +Utilizing the API +================= +In order to enable ad-hoc authentication-providers or to use WSGI-servers +not supported by *bottle* out-of-the-box, you needed to launch *pypiserver* +via its API. -Pypiserver can also be run via the API. The only additional feature that this -enables is the use of alternative authentication mechanisms. The ``auther`` -keyword can be passed to the pypiserver app with any callable as a value. The -associated callable should return a boolean when passed the username and the -password for a given request. - -For example, to authenticate users based on the ``/etc/passwd`` file under Unix, -you may delegate such decisions to the `python-pam`_ by following these steps. - -1. Ensure ``python-pam`` module is installed:: - - pip install python-pam - -2. Create a python-script along these lines:: - - $ cat > pypiserver-start.py - import pypiserver - from pypiserver import bottle - import pam - pypiserver.app(root='./packages', auther=pam.authenticate) - bottle.run(app=app, host='0.0.0.0', port=80, server='auto') - - [Ctrl+ D] - -3. Invoke the python-script to start-up *pypiserver*:: - - $ python pypiserver-start.py +- The main entry-point for configuring *pypiserver* is the `pypiserver:app() + `_ + function. This function returns the internal WSGI-app that you my then + send to any WSGI-server you like. -.. Note:: - The `python-pam`_ module, requires *read* access to ``/etc/shadow`` file; - you may add the user under which *pypiserver* runs into the *shadow* - group, with a command like this: ``sudo usermod -a -G shadow pypy-user``. +- To get all ``pypiserver:app()`` keywords and their explanations, read the + function `pypiserver:default_config() + `_. +- Finally, to fire-up a WSGI-server with the configured app, invoke + the ``bottle:run(app, host, port, server)`` function. + Note that *pypiserver* ships with it's own copy of *bottle*; to use it, + import it like that: ``from pypiserver import bottle`` -Using a different WSGI server +Using a different WSGI-server ----------------------------- -- *pypiserver* ships with it's own copy of *bottle*. - It's possible to use bottle with different WSGI servers. +- The *bottle* web-server which supports many WSGI-servers, among others, + *paste*, *cherrypy*, *twisted* and *wsgiref* (part of python); you select + them using the ``--server`` flag. -- *bottle* may use any of *paste*, *cherrypy*, *twisted* and *wsgiref* - (part of python) if available, using the ``--server`` flag. +- You may view all supported WSGI servers using the following interactive code:: -- If none of the above servers matches your needs, use the API to get - the internal WSGI app, which you can then run under any WSGI server you like. - ``pypiserver.app`` has the following interface:: + >>> from pypiserver import bottle + >>> list(bottle.server_names.keys()) + ['cgi', 'gunicorn', 'cherrypy', 'eventlet', 'tornado', 'geventSocketIO', + 'rocket', 'diesel', 'twisted', 'wsgiref', 'fapws3', 'bjoern', 'gevent', + 'meinheld', 'auto', 'aiohttp', 'flup', 'gae', 'paste', 'waitress'] - def app(root=None, - redirect_to_fallback=True, - fallback_url="http://pypi.python.org/simple") - - and returns the WSGI application. `root` is the package directory, - `redirect_to_fallback` specifies whether to redirect to `fallback_url` when - a package is missing. +- If none of the above servers matches your needs, invoke just the + ``pypiserver:app()`` method which returns the internal WSGI-app WITHOUT + starting-up a server - you may then send it to any WSGI-server you like. gunicorn @@ -632,6 +613,41 @@ unstable packages on different paths:: gunicorn_paster paste.ini +Using Ad-hoc authentication providers +------------------------------------- +The ``auther`` keyword of ``pypiserver:app()`` function maybe set only using +the API. This can be any callable that returns a boolean when passed +the *username* and the *password* for a given request. + +For example, to authenticate users based on the ``/etc/passwd`` file under Unix, +you may delegate such decisions to the `python-pam`_ library by following +these steps: + +1. Ensure ``python-pam`` module is installed:: + + pip install python-pam + +2. Create a python-script along these lines:: + + $ cat > pypiserver-start.py + import pypiserver + from pypiserver import bottle + import pam + pypiserver.app(root='./packages', auther=pam.authenticate) + bottle.run(app=app, host='0.0.0.0', port=80, server='auto') + + [Ctrl+ D] + +3. Invoke the python-script to start-up *pypiserver*:: + + $ python pypiserver-start.py + + +.. Note:: + The `python-pam`_ module, requires *read* access to ``/etc/shadow`` file; + you may add the user under which *pypiserver* runs into the *shadow* + group, with a command like this: ``sudo usermod -a -G shadow pypy-user``. + Sources diff --git a/pypiserver/__init__.py b/pypiserver/__init__.py index 7903bb0..4132854 100644 --- a/pypiserver/__init__.py +++ b/pypiserver/__init__.py @@ -72,6 +72,7 @@ def default_config( found in the roots. :param root: A list of paths, derived from the packages specified on cmd-line. + If `None`, defaults to '~/packages'. :param redirect_to_fallback: see :option:`--disable-fallback` :param authenticated: