Commits

Anonymous committed ede3612

update docs, Sphinxify

Comments (0)

Files changed (7)

devauth/__init__.py

 from tempita import HTMLTemplate
 from devauth.htpasswd import check_password, NoSuchUser
 
+__all__ = ['DevAuth', 'make_middleware']
+
 class DevAuth(object):
     """
     This is an authentication middleware for developer tools.
+:mod:`devauth` code -- Developer-oriented WSGI authentication
+=============================================================
+
+.. automodule:: devauth
+
+Module Contents
+---------------
+
+.. autoclass:: DevAuth
+   :members:
+
+.. autofunction:: make_middleware
+
+# -*- coding: utf-8 -*-
+#
+# Paste documentation build configuration file, created by
+# sphinx-quickstart on Tue Apr 22 22:08:49 2008.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default value; values that are commented out
+# serve to show the default value.
+
+import sys
+
+# If your extensions are in another directory, add it here.
+#sys.path.append('some/directory')
+
+# General configuration
+# ---------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.txt'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+project = 'DevAuth'
+copyright = '2009, Ian Bicking'
+
+# The default replacements for |version| and |release|, also used in various
+# other places throughout the built documents.
+#
+# The short X.Y version.
+version = '0.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.1'
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+unused_docs = []
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for HTML output
+# -----------------------
+
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+html_style = 'default.css'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Content template for the index page.
+#html_index = ''
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+#html_copy_source = True
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'DevAuthdoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+#latex_documents = []
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
 DevAuth
 =======
 
+.. toctree::
+   :maxdepth: 1
+
+   news
+   license
+   code
+
 .. contents::
 
 Introduction
 ------------
 
-This middleware is written to provide developer access to
-web-accessible developer tools.  It is an authentication system, it
-does not itself provide any tools.  It is *only* intended for
-developers, and is not an authentication system that is usable in
-general-purpose applications.
+Many debugging tools provide through-the-web functionality that is
+private, important to secure, and orthogonal to any other
+authentication on the system.  DevAuth is a tool to provide a single
+way to restrict access to these tools.
+
+DevAuth is only an authentication system, it does not itself provide
+any tools.  It is *only* intended for developers, and is not an
+authentication system that is usable in general-purpose applications.
 
 This is written for `the wsgi.org developer_auth spec
 <http://wsgi.org/wsgi/Specifications/developer_auth>`_.
 
-Usage
------
+Authentication
+--------------
+
+There are two means of authentication that DevAuth uses:
+username/password authentication, and IP-based restrictions.  Ideally
+you would use both of these for higher security.  It may also be
+reasonable to use an IP restriction of 127.0.0.1 for local
+development.
+
+Username/password authentication can be done with a function that
+checks the username and password (like ``valid_login =
+password_checker(username, password)``), or with an Apache
+htpasswd-style file.
+
+IP based authentication uses ``deny`` and ``allow``.  If you give IP
+addresses that are denied, these are entirely rejected; if you give IP
+addresses that are allowed, then only requests from these IP addresses
+are allowed.  ``deny`` takes precedence over ``allow``.  These can be
+lists of IP addresses (with commas), `IP masks
+<http://wiki.xtronics.com/index.php/IP_Subnet_Masks>`_ (like
+``192.168.0.0/24``) or ranges like ``192.168.1<->3`` (meaning
+192.168.{1-3}.*).
+
+Any change in the developer's IP address will require re-login.
+Logins may expire (if so configured) and require re-login.
+
+Usage/Configuration
+-------------------
+
+The basic usage of DevAuth is like::
+
+  from devauth import DevAuth
+
+  app = ... instantiate main app ...
+  wrapped_app = DevAuth(app, ...configuration...)
+
+The configuration is keyword arguments:
+
+``allow``:
+    The allowed IP addresses.  This can be a string or a list of
+    strings.  See `Authentication`_ for the allowed formats.  This
+    defaults to ``"127.0.0.1"``, i.e., only local access is allowed.
+    None means allow any IP address.  Note both
+    ``environ['REMOTE_ADDR']`` and ``environ['HTTP_X_FORWARDED_FOR']``
+    are checked, and both must pass.
+
+``deny``:
+    Similar to ``allow``, except any requests from IP addresses
+    matching these IP addresses will not be allowed to login.
+
+``password_file``:
+    This is a filename, the location of a password file as generated
+    by `htpasswd
+    <http://httpd.apache.org/docs/2.0/programs/htpasswd.html>`_.  You
+    can create this file like::
+
+        $ htpasswd -s devauth.htpasswd username
+        New password: 
+        Re-type new password: 
+        Adding password for user username
+
+    You must use the argument ``-c`` to first create the file (without
+    it an entry will be appended).  ``-s`` hashes your password with
+    SHA; any hash supported by htpasswd will work, but SHA is better
+    than the default.
+
+``password_checker``:
+    This is a function to check the username and password.  A very
+    simple implementation might be::
+
+        def password_checker(username, password):
+            return username == 'admin' and password='topsecret'
+
+``secret_file``, ``secret``:
+    DevAuth uses a server-side secret to sign the login cookies.  You
+    can keep this secret in a file or provide it directly.  If you
+    give it a filename and the file doesn't exist, a file will be
+    created with a randomly generated secret (it is advantageous to
+    keep it in a file because it will persist over restarts, so
+    developers won't have to re-login).
+
+    The default is to keep the secret in ``$TMP/devauth.txt``, where
+    ``$TMP`` is replaced with the appropriate system temporary
+    directory.
+
+``logger``:
+    A `logging <http://docs.python.org/library/logging.html>`_ logger
+    instance, or the name of a logger.  If not given a logger is
+    created with the name ``DevAuth``.  This logs logins, failed
+    logins, problems with signed keys, etc.
+
+``expiration``:
+    The number of minutes the login is valid for (None means no
+    expiration).  This is counted from the time of login, so even if
+    you maintain activity the login will still expire.
+
+``login_mountpoint``:
+    This is the URL where the login will take place, it defaults to
+    ``/.devauth``.  Then the login is at ``/.devauth/login`` and the
+    logout is at ``/.devauth/logout``.  Only these two URLs are
+    intercepted, so you can still have things at other URLs like
+    ``/.devauth/logs`` (if you do this, you'll probably replace
+    ``/.devauth`` with something specific to your application).
+
+Paste Deploy Configuration
+--------------------------
 
 You can use this with `Paste Deploy configuration
 <http://pythonpaste.org/deploy/>`_ (as used in Pylons and Repoze).  It
 -------------------
 
 If you want to check if a developer is logged in, look for
-``environ['x-wsgiorg.developer_user']``.  If the page is for
-developers only, then return ``403 Forbidden``.
-
-News
-----
-
-svn trunk
-~~~~~~~~~
-
-* Change the secret file default location to use the ``TEMP`` variable
-  (and other variables as read by ``tempfile``) for its location,
-  instead of simply being hardcoded to ``/tmp/devauth.txt``.
+``environ['x-wsgiorg.developer_user']``.  This key will have the
+username as a value.  If the page is for developers only, then return
+``403 Forbidden``.
-Copyright (c) 2007 Ian Bicking and Contributors
+DevAuth License
+---------------
+
+Copyright (c) 2009 Ian Bicking and Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
+News
+----
+
+svn trunk
+~~~~~~~~~
+
+* Change the secret file default location to use the ``TEMP`` variable
+  (and other variables as read by ``tempfile``) for its location,
+  instead of simply being hardcoded to ``/tmp/devauth.txt``.
+#!/bin/sh
+
+CMD="$1"
+if [ "$CMD" = "release" ] ; then
+  python -c 'import setuptools; __file__="setup.py"; execfile(__file__)' register sdist upload
+  CMD="publish"
+fi
+
+mkdir -p docs/_static docs/_build
+sphinx-build -E -b html docs/ docs/_build || exit 1
+if [ "$CMD" = "publish" ] ; then
+  cd docs/_build
+  echo "Uploading files..."
+  tar czvf - . | ssh flow.openplans.org 'ssh acura.openplans.org "cd /www/devauth.openplans.org/; tar xzvf -"'
+fi