From 86175054d63df56c4f3c79108d363ef5e127e440 Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Fri, 17 Jun 2011 20:27:25 +0200 Subject: [PATCH] More docstrings for blueprints. --- docs/api.rst | 9 ++++++--- docs/patterns/appfactories.rst | 4 ++-- docs/quickstart.rst | 3 +-- flask/blueprints.py | 35 ++++++++++++++++++++++++++++++---- 4 files changed, 40 insertions(+), 11 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index b3953537..62f5e01d 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -18,10 +18,10 @@ Application Object :inherited-members: -Module Objects --------------- +Blueprint Objects +----------------- -.. autoclass:: Module +.. autoclass:: Blueprint :members: :inherited-members: @@ -350,6 +350,9 @@ Useful Internals if ctx is not None: return ctx.session +.. autoclass:: flask.blueprints.BlueprintSetupState + :members: + Signals ------- diff --git a/docs/patterns/appfactories.rst b/docs/patterns/appfactories.rst index 134ffcf4..09884790 100644 --- a/docs/patterns/appfactories.rst +++ b/docs/patterns/appfactories.rst @@ -3,8 +3,8 @@ Application Factories ===================== -If you are already using packages and modules for your application -(:ref:`packages`) there are a couple of really nice ways to further improve +If you are already using packages and blueprints for your application +(:ref:`blueprints`) there are a couple of really nice ways to further improve the experience. A common pattern is creating the application object when the module is imported. But if you move the creation of this object, into a function, you can then create multiple instances of this and later. diff --git a/docs/quickstart.rst b/docs/quickstart.rst index fc5ae0f1..3875b296 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -381,8 +381,7 @@ package it's actually inside your package: /hello.html For templates you can use the full power of Jinja2 templates. Head over -to the :ref:`templating` section of the documentation or the official -`Jinja2 Template Documentation +to the the official `Jinja2 Template Documentation `_ for more information. Here is an example template: diff --git a/flask/blueprints.py b/flask/blueprints.py index 181f0c16..4a3f531a 100644 --- a/flask/blueprints.py +++ b/flask/blueprints.py @@ -16,25 +16,46 @@ from .helpers import _PackageBoundObject, _endpoint_from_view_func class BlueprintSetupState(object): """Temporary holder object for registering a blueprint with the - application. + application. An instance of this class is created by the + :meth:`~flask.Blueprint.make_setup_state` method and later passed + to all register callback functions. """ def __init__(self, blueprint, app, options, first_registration): + #: a reference to the current application self.app = app + + #: a reference to the blurprint that created this setup state. self.blueprint = blueprint + + #: a dictionary with all options that were passed to the + #: :meth:`~flask.Flask.register_blueprint` method. self.options = options + + #: as blueprints can be registered multiple times with the + #: application and not everything wants to be registered + #: multiple times on it, this attribute can be used to figure + #: out if the blueprint was registered in the past already. self.first_registration = first_registration subdomain = self.options.get('subdomain') if subdomain is None: subdomain = self.blueprint.subdomain + + #: The subdomain that the blueprint should be active for, `None` + #: otherwise. self.subdomain = subdomain url_prefix = self.options.get('url_prefix') if url_prefix is None: url_prefix = self.blueprint.url_prefix + + #: The prefix that should be used for all URLs defined on the + #: blueprint. self.url_prefix = url_prefix + #: A dictionary with URL defaults that is added to each and every + #: URL that was defined with the blueprint. self.url_defaults = dict(self.blueprint.url_defaults) self.url_defaults.update(self.options.get('url_defaults', ())) @@ -56,7 +77,11 @@ class BlueprintSetupState(object): class Blueprint(_PackageBoundObject): - """Represents a blueprint. + """Represents a blueprint. A blueprint is an object that records + functions that will be called with the + :class:`~flask.blueprint.BlueprintSetupState` later to register functions + or other things on the main application. See :ref:`blueprints` for more + information. .. versionadded:: 0.7 """ @@ -104,6 +129,10 @@ class Blueprint(_PackageBoundObject): return self.record(update_wrapper(wrapper, func)) def make_setup_state(self, app, options, first_registration=False): + """Creates an instance of :meth:`~flask.blueprints.BlueprintSetupState` + object that is later passed to the register callback functions. + Subclasses can override this to return a subclass of the setup state. + """ return BlueprintSetupState(self, app, options, first_registration) def register(self, app, options, first_registration=False): @@ -254,8 +283,6 @@ class Blueprint(_PackageBoundObject): Otherwise works as the :meth:`~flask.Flask.errorhandler` decorator of the :class:`~flask.Flask` object. - - .. versionadded:: 0.7 """ def decorator(f): self.record_once(lambda s: s.app._register_error_handler(