stackforge/pecan
Code Issues Proposed changes

Appease Sphinx

Browse Source 
Fixes to docs and DocStrings to silence sphinx warnings and errors
during 'make html':
 - bad indentation in param blocks
 - unsupported section header markup in DocStrings
 - touched docs/source/static (sphinx does not like not having it)
Fixes to DocStrings to make sphinx display paragraphs as intended:
 - .. notes:: not .. 🎶: makes notes show up
 - for reasons undefined sphinx appears to ignore DocStrings in
   __init__; moved the params documentation up to the main class
   DocString.
This commit is contained in:
Pete
2012-03-16 15:53:05 -07:00
parent 49c99eac32
commit f96bfa1e80
5 changed files with 68 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
docs/source/static Normal file
View File

20
pecan/configuration.py
View File

@@ -29,16 +29,15 @@ class ConfigDict(dict):
class Config(object):
'''
Base class for Pecan configurations.
Create a Pecan configuration object from a dictionary or a
filename.
:param conf_dict: A python dictionary to use for the configuration.
:param filename: A filename to use for the configuration.
'''
def __init__(self, conf_dict={}, filename=''):
'''
Create a Pecan configuration object from a dictionary or a
filename.
:param conf_dict: A python dictionary to use for the configuration.
:param filename: A filename to use for the configuration.
'''
self.__values__ = {}
self.__file__ = filename
@@ -52,7 +51,7 @@ class Config(object):
Updates this configuration with a dictionary.
:param conf_dict: A python dictionary to update this configuration
with.
with.
'''
if isinstance(conf_dict, dict):
@@ -96,7 +95,7 @@ class Config(object):
Converts recursively the Config object into a valid dictionary.
:param prefix: A string to optionally prefix all key elements in the
returned dictonary.
returned dictonary.
'''
conf_obj = dict(self)
@@ -186,8 +185,7 @@ def set_config(config, overwrite=False):
Updates the global configuration.
:param config: Can be a dictionary containing configuration, or a string
which
represents a (relative) configuration filename.
which represents a (relative) configuration filename.
'''
if overwrite is True:

52
pecan/core.py
View File

@@ -49,7 +49,7 @@ def override_template(template, content_type=None):
your response.
:param template: a valid path to a template file, just as you would specify
in an ``@expose``.
in an ``@expose``.
:param content_type: a valid MIME type to use for the response.func_closure
'''
@@ -86,10 +86,10 @@ def redirect(location=None, internal=False, code=None, headers={},
:param location: The HTTP location to redirect to.
:param internal: A boolean indicating whether the redirect should be
internal.
internal.
:param code: The HTTP status code to use for the redirect. Defaults to 302.
:param headers: Any HTTP headers to send with the response, as a
dictionary.
dictionary.
'''
if add_slash:
@@ -123,9 +123,9 @@ def render(template, namespace):
controller where you have no template specified in the ``@expose``.
:param template: The path to your template, as you would specify in
``@expose``.
``@expose``.
:param namespace: The namespace to use for rendering the template, as a
dictionary.
dictionary.
'''
return state.app.render(template, namespace)
@@ -137,8 +137,9 @@ def load_app(config):
configuration.
:param config: Can be a dictionary containing configuration, or a string
which represents a (relative) configuration filename.
:returns a pecan.Pecan object
which represents a (relative) configuration filename.
returns a pecan.Pecan object
'''
from configuration import _runtime_conf, set_config
set_config(config, overwrite=True)
@@ -158,6 +159,22 @@ class Pecan(object):
'''
Base Pecan application object. Generally created using ``pecan.make_app``,
rather than being created manually.
Creates a Pecan application instance, which is a WSGI application.
:param root: A string representing a root controller object (e.g.,
"myapp.controller.root.RootController")
:param default_renderer: The default rendering engine to use. Defaults
to mako.
:param template_path: The default relative path to use for templates.
Defaults to 'templates'.
:param hooks: A list of Pecan hook objects to use for this application.
:param custom_renderers: Custom renderer objects, as a dictionary keyed
by engine name.
:param extra_template_vars: Any variables to inject into the template
namespace automatically.
:param force_canonical: A boolean indicating if this project should
require canonical URLs.
'''
def __init__(self, root,
@@ -169,21 +186,6 @@ class Pecan(object):
force_canonical=True
):
'''
Creates a Pecan application instance, which is a WSGI application.
:param root: A string representing a root controller object (e.g.,
"myapp.controller.root.RootController")
:param default_renderer: The default rendering engine to use. Defaults
to mako.
:param template_path: The default relative path to use for templates.
Defaults to 'templates'.
:param hooks: A list of Pecan hook objects to use for this application.
:param custom_renderers: Custom renderer objects, as a dictionary keyed
by engine name.
:param extra_template_vars: Any variables to inject into the template
namespace automatically.
:param force_canonical: A boolean indicating if this project should
require canonical URLs.
'''
if isinstance(root, basestring):
@@ -254,7 +256,7 @@ class Pecan(object):
Determines the hooks to be run, in which order.
:param controller: If specified, includes hooks for a specific
controller.
controller.
'''
controller_hooks = []
@@ -272,8 +274,8 @@ class Pecan(object):
Processes hooks of the specified type.
:param hook_type: The type of hook, including ``before``, ``after``,
``on_error``, and ``on_route``.
:param *args: Arguments to pass to the hooks.
``on_error``, and ``on_route``.
:param \*args: Arguments to pass to the hooks.
'''
if hook_type in ['before', 'on_route']:

16
pecan/decorators.py
View File

@@ -27,12 +27,12 @@ def expose(template=None,
access via HTTP, and to configure that access.
:param template: The path to a template, relative to the base template
directory.
directory.
:param content_type: The content-type to use for this template.
:param generic: A boolean which flags this as a "generic" controller, which
uses generic functions based upon ``simplegeneric`` generic functions.
Allows you to split a single controller into multiple paths based upon HTTP
method.
:param generic: A boolean which flags this as a "generic" controller,
which uses generic functions based upon ``simplegeneric``
generic functions. Allows you to split a single
controller into multiple paths based upon HTTP method.
'''
if template == 'json':
@@ -69,7 +69,7 @@ def transactional(ignore_redirects=True):
regardless of HTTP method.
:param ignore_redirects: Indicates if the hook should ignore redirects
for this controller or not.
for this controller or not.
'''
def deco(f):
@@ -115,7 +115,7 @@ def after_commit(action):
commit is successfully issued.
:param action: The callable to call after the commit is successfully
issued.
issued.
'''
return after_action('commit', action)
@@ -127,7 +127,7 @@ def after_rollback(action):
rollback is successfully issued.
:param action: The callable to call after the rollback is successfully
issued.
issued.
'''
return after_action('rollback', action)

49
pecan/hooks.py
View File

@@ -91,6 +91,14 @@ class PecanHook(object):
class TransactionHook(PecanHook):
'''
:param start: A callable that will bind to a writable database and
start a transaction.
:param start_ro: A callable that will bind to a readable database.
:param commit: A callable that will commit the active transaction.
:param rollback: A callable that will roll back the active
transaction.
:param clear: A callable that will clear your current context.
A basic framework hook for supporting wrapping requests in
transactions. By default, it will wrap all but ``GET`` and ``HEAD``
requests in a transaction. Override the ``is_transactional`` method
@@ -98,15 +106,6 @@ class TransactionHook(PecanHook):
'''
def __init__(self, start, start_ro, commit, rollback, clear):
'''
:param start: A callable that will bind to a writable database and
start a transaction.
:param start_ro: A callable that will bind to a readable database.
:param commit: A callable that will commit the active transaction.
:param rollback: A callable that will roll back the active
transaction.
:param clear: A callable that will clear your current context.
'''
self.start = start
self.start_ro = start_ro
@@ -196,6 +195,15 @@ class TransactionHook(PecanHook):
class RequestViewerHook(PecanHook):
'''
:param config: A (optional) dictionary that can hold ``items`` and/or
``blacklist`` keys.
:param writer: The stream writer to use. Can redirect output to other
streams as long as the passed in stream has a
``write`` callable method.
:param terminal: Outputs to the chosen stream writer (usually
the terminal)
:param headers: Sets values to the X-HTTP headers
Returns some information about what is going on in a single request. It
accepts specific items to report on but uses a default list of items when
none are passed in. Based on the requested ``url``, items can also be
@@ -203,8 +211,8 @@ class RequestViewerHook(PecanHook):
Configuration is flexible, can be passed in (or not) and can contain
some or all the keys supported.
``items``
---------
**items**
This key holds the items that this hook will display. When this key is
passed only the items in the list will be used. Valid items are *any*
item that the ``request`` object holds, by default it uses the
@@ -217,11 +225,11 @@ class RequestViewerHook(PecanHook):
* params
* hooks
.. :note::
.. note::
This key should always use a ``list`` of items to use.
``blacklist``
-------------
**blacklist**
This key holds items that will be blacklisted based on ``url``. If
there is a need to ommit urls that start with `/javascript`, then this
key would look like::
@@ -232,7 +240,7 @@ class RequestViewerHook(PecanHook):
will verify that the url is not starting with items in this list to display
results, otherwise it will get ommited.
.. :note::
.. note::
This key should always use a ``list`` of items to use.
For more detailed documentation about this hook, please see
@@ -243,16 +251,7 @@ class RequestViewerHook(PecanHook):
def __init__(self, config=None, writer=sys.stdout, terminal=True,
headers=True):
'''
:param config: A (optional) dictionary that can hold ``items`` and/or
``blacklist`` keys.
:param writer: The stream writer to use. Can redirect output to other
streams as long as the passed in stream has a
``write`` callable method.
:param terminal: Outputs to the chosen stream writer (usually
the terminal)
:param headers: Sets values to the X-HTTP headers
'''
if not config:
self.config = {'items': self.available}
else: