From: Stephen Burrows Date: Tue, 10 May 2011 21:07:07 +0000 (-0400) Subject: Added/tweaked docs for exceptions, middleware, and signals. Minor formatting tweaks... X-Git-Tag: philo-0.9~12^2~21 X-Git-Url: http://git.ithinksw.org/philo.git/commitdiff_plain/344bace6dc955286a59480e8bf538ab524a7ee9f?ds=sidebyside;hp=--cc Added/tweaked docs for exceptions, middleware, and signals. Minor formatting tweaks to View and TreeManager docstrings. --- 344bace6dc955286a59480e8bf538ab524a7ee9f diff --git a/docs/dummy-settings.py b/docs/dummy-settings.py index e69de29..7e424ab 100644 --- a/docs/dummy-settings.py +++ b/docs/dummy-settings.py @@ -0,0 +1,6 @@ +DATABASES = { + 'default': { + 'ENGINE': 'django.db.backends.sqlite3', + 'NAME': 'db.sl3' + } +} \ No newline at end of file diff --git a/docs/exceptions.rst b/docs/exceptions.rst new file mode 100644 index 0000000..679ac77 --- /dev/null +++ b/docs/exceptions.rst @@ -0,0 +1,5 @@ +Exceptions +========== + +.. automodule:: philo.exceptions + :members: MIDDLEWARE_NOT_CONFIGURED, AncestorDoesNotExist, ViewCanNotProvideSubpath, ViewDoesNotProvideSubpaths \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index cfc7136..a1490b3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,9 @@ Contents: intro models/intro + exceptions + middleware + signals Indices and tables ================== diff --git a/docs/middleware.rst b/docs/middleware.rst new file mode 100644 index 0000000..4a5c05f --- /dev/null +++ b/docs/middleware.rst @@ -0,0 +1,5 @@ +Middleware +========== + +.. automodule:: philo.middleware + :members: diff --git a/docs/models/fields.rst b/docs/models/fields.rst index 91164a3..0b3d0f9 100644 --- a/docs/models/fields.rst +++ b/docs/models/fields.rst @@ -5,7 +5,7 @@ Custom Fields :members: EntityProxyFields -================= +----------------- .. automodule:: philo.models.fields.entities :members: \ No newline at end of file diff --git a/docs/signals.rst b/docs/signals.rst new file mode 100644 index 0000000..8b3da3c --- /dev/null +++ b/docs/signals.rst @@ -0,0 +1,5 @@ +Signals +======= + +.. automodule:: philo.signals + :members: diff --git a/philo/exceptions.py b/philo/exceptions.py index f53083d..9a8908e 100644 --- a/philo/exceptions.py +++ b/philo/exceptions.py @@ -1,19 +1,20 @@ from django.core.exceptions import ImproperlyConfigured +#: Raised if ``request.node`` is required but not present. For example, this can be raised by :func:`philo.views.node_view`. :data:`MIDDLEWARE_NOT_CONFIGURED` is an instance of :exc:`django.core.exceptions.ImproperlyConfigured`. MIDDLEWARE_NOT_CONFIGURED = ImproperlyConfigured("""Philo requires the RequestNode middleware to be installed. Edit your MIDDLEWARE_CLASSES setting to insert 'philo.middleware.RequestNodeMiddleware'.""") class ViewDoesNotProvideSubpaths(Exception): - """ Raised by View.reverse when the View does not provide subpaths (the default). """ + """Raised by :meth:`View.reverse` when the View does not provide subpaths (the default).""" silent_variable_failure = True class ViewCanNotProvideSubpath(Exception): - """ Raised by View.reverse when the View can not provide a subpath for the supplied arguments. """ + """Raised by :meth:`View.reverse` when the :class:`View` can not provide a subpath for the supplied arguments.""" silent_variable_failure = True class AncestorDoesNotExist(Exception): - """ Raised by get_path if the root model is not an ancestor of the current model """ + """Raised by :meth:`TreeModel.get_path` if the root instance is not an ancestor of the current instance.""" pass \ No newline at end of file diff --git a/philo/middleware.py b/philo/middleware.py index 4082d4b..b90067a 100644 --- a/philo/middleware.py +++ b/philo/middleware.py @@ -44,7 +44,7 @@ class LazyNode(object): class RequestNodeMiddleware(object): - """Middleware to process the request's path and attach the closest ancestor node.""" + """Adds a ``node`` attribute, representing the currently-viewed node, to every incoming :class:`HttpRequest` object. This is required by :func:`philo.views.node_view`.""" def process_request(self, request): request.__class__.node = LazyNode() diff --git a/philo/models/base.py b/philo/models/base.py index 436df42..1726d19 100644 --- a/philo/models/base.py +++ b/philo/models/base.py @@ -344,7 +344,7 @@ class TreeManager(models.Manager): def get_with_path(self, path, root=None, absolute_result=True, pathsep='/', field='slug'): """ - If ``absolute_result`` is ``True``, returns the object at ``path`` (starting at ``root``) or raises a :class:`DoesNotExist` exception. Otherwise, returns a tuple containing the deepest object found along ``path`` (or ``root`` if no deeper object is found) and the remainder of the path after that object as a string (or None if there is no remaining path). + If ``absolute_result`` is ``True``, returns the object at ``path`` (starting at ``root``) or raises an :class:`~django.core.exceptions.ObjectDoesNotExist` exception. Otherwise, returns a tuple containing the deepest object found along ``path`` (or ``root`` if no deeper object is found) and the remainder of the path after that object as a string (or None if there is no remaining path). .. note:: If you are looking for something with an exact path, it is faster to use absolute_result=True, unless the path depth is over ~40, in which case the high cost of the absolute query may make a binary search (i.e. non-absolute) faster. @@ -355,7 +355,8 @@ class TreeManager(models.Manager): :param absolute_result: Whether to return an absolute result or do a binary search :param pathsep: The path separator used in ``path`` :param field: The field on the model which should be queried for ``path`` segment matching. - :returns: An instance if absolute_result is True or (instance, remaining_path) otherwise. + :returns: An instance if ``absolute_result`` is ``True`` or an (instance, remaining_path) tuple otherwise. + :raises django.core.exceptions.ObjectDoesNotExist: if no object can be found matching the input parameters. """ diff --git a/philo/models/nodes.py b/philo/models/nodes.py index 2d4639f..899303f 100644 --- a/philo/models/nodes.py +++ b/philo/models/nodes.py @@ -133,17 +133,14 @@ class View(Entity): If ``obj`` is provided, :meth:`get_reverse_params` will be called and the results will be combined with any ``view_name``, ``args``, and ``kwargs`` that may have been passed in. - This method will raise the following exceptions: - - - :class:`~philo.exceptions.ViewDoesNotProvideSubpaths` if :attr:`accepts_subpath` is False. - - :class:`~philo.exceptions.ViewCanNotProvideSubpath` if a reversal is not possible. - :param view_name: The name of the view to be reversed. :param args: Extra args for reversing the view. :param kwargs: A dictionary of arguments for reversing the view. :param node: The node whose subpath this is. :param obj: An object to be passed to :meth:`get_reverse_params` to generate a view_name, args, and kwargs for reversal. :returns: A subpath beyond the node that reverses the view, or an absolute url that reverses the view if a node was passed in. + :except philo.exceptions.ViewDoesNotProvideSubpaths: if :attr:`accepts_subpath` is False + :except philo.exceptions.ViewCanNotProvideSubpath: if a reversal is not possible. """ if not self.accepts_subpath: diff --git a/philo/signals.py b/philo/signals.py index 3653c54..558c6fe 100644 --- a/philo/signals.py +++ b/philo/signals.py @@ -1,8 +1,60 @@ from django.dispatch import Signal +#: Sent whenever an Entity subclass has been "prepared" -- that is, after the processing necessary to make :mod:`EntityProxyFields ` work has been completed. This will fire after :obj:`django.db.models.signals.class_prepared`. +#: +#: Arguments that are sent with this signal: +#: +#: ``sender`` +#: The model class. entity_class_prepared = Signal(providing_args=['class']) + +#: Sent when a :class:`~philo.models.nodes.View` instance is about to render. This allows you, for example, to modify the ``extra_context`` dictionary used in rendering. +#: +#: Arguments that are sent with this signal: +#: +#: ``sender`` +#: The :class:`~philo.models.nodes.View` instance +#: +#: ``request`` +#: The :class:`HttpRequest` instance which the :class:`~philo.models.nodes.View` is rendering in response to. +#: +#: ``extra_context`` +#: A dictionary which will be passed into :meth:`~philo.models.nodes.View.actually_render_to_response`. view_about_to_render = Signal(providing_args=['request', 'extra_context']) + +#: Sent when a view instance has finished rendering. +#: +#: Arguments that are sent with this signal: +#: +#: ``sender`` +#: The :class:`~philo.models.nodes.View` instance +#: +#: ``response`` +#: The :class:`HttpResponse` instance which :class:`~philo.models.nodes.View` view has rendered to. view_finished_rendering = Signal(providing_args=['response']) + +#: Sent when a :class:`~philo.models.pages.Page` instance is about to render as a string. If the :class:`~philo.models.pages.Page` is rendering as a response, this signal is sent after :obj:`view_about_to_render` and serves a similar function. However, there are situations where a :class:`~philo.models.pages.Page` may be rendered as a string without being rendered as a response afterwards. +#: +#: Arguments that are sent with this signal: +#: +#: ``sender`` +#: The :class:`~philo.models.pages.Page` instance +#: +#: ``request`` +#: The :class:`HttpRequest` instance which the :class:`~philo.models.pages.Page` is rendering in response to (if any). +#: +#: ``extra_context`` +#: A dictionary which will be passed into the :class:`Template` context. page_about_to_render_to_string = Signal(providing_args=['request', 'extra_context']) + +#: Sent when a :class:`~philo.models.pages.Page` instance has just finished rendering as a string. If the :class:`~philo.models.pages.Page` is rendering as a response, this signal is sent before :obj:`view_finished_rendering` and serves a similar function. However, there are situations where a :class:`~philo.models.pages.Page` may be rendered as a string without being rendered as a response afterwards. +#: +#: Arguments that are sent with this signal: +#: +#: ``sender`` +#: The :class:`~philo.models.pages.Page` instance +#: +#: ``string`` +#: The string which the :class:`~philo.models.pages.Page` has rendered to. page_finished_rendering_to_string = Signal(providing_args=['string']) \ No newline at end of file