Anonymous committed ede3612

update docs, Sphinxify

Comments (0)

Files changed (7)


 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.
+# 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
+.. toctree::
+   :maxdepth: 1
+   news
+   license
+   code
 .. contents::
-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 developer_auth spec
+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 for local
+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
+<>`_ (like
+````) or ranges like ``192.168.1<->3`` (meaning
+Any change in the developer's IP address will require re-login.
+Logins may expire (if so configured) and require re-login.
+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:
+    The allowed IP addresses.  This can be a string or a list of
+    strings.  See `Authentication`_ for the allowed formats.  This
+    defaults to ``""``, 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.
+    Similar to ``allow``, except any requests from IP addresses
+    matching these IP addresses will not be allowed to login.
+    This is a filename, the location of a password file as generated
+    by `htpasswd
+    <>`_.  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.
+    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.
+    A `logging <>`_ 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.
+    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.
+    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
 <>`_ (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``.
-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
+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``.
+if [ "$CMD" = "release" ] ; then
+  python -c 'import setuptools; __file__=""; execfile(__file__)' register sdist upload
+  CMD="publish"
+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 'ssh "cd /www/; tar xzvf -"'