10000 the canonical import location for HTTP exceptions/responses is now py… · alex-python/pyramid@a7e6257 · GitHub
[go: up one dir, main page]
Skip to content

Commit a7e6257

Browse files
mcdoncmcdonc
committed
the canonical import location for HTTP exceptions/responses is now pyramid.response
1 parent 966b5cf commit a7e6257

35 files changed

+1618
-1575
lines changed

‎docs/glossary.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -594,7 +594,7 @@ Glossary
594594

595595
Not Found view
596596
An :term:`exception view` invoked by :app:`Pyramid` when the
597-
developer explicitly raises a ``pyramid.exceptions.NotFound``
597+
developer explicitly raises a ``pyramid.response.HTTPNotFound``
598598
exception from within :term:`view` code or :term:`root factory`
599599
code, or when the current request doesn't match any :term:`view
600600
configuration`. :app:`Pyramid` provides a default
@@ -604,7 +604,7 @@ Glossary
604604
Forbidden view
605605
F438 An :term:`exception view` invoked by :app:`Pyramid` when the
606606
developer explicitly raises a
607-
``pyramid.exceptions.Forbidden`` exception from within
607+
``pyramid.response.HTTPForbidden`` exception from within
608608
:term:`view` code or :term:`root factory` code, or when the
609609
:term:`view configuration` and :term:`authorization policy`
610610
found for a request disallows a particular view invocation.

‎docs/narr/hooks.rst

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ configuration.
2121

2222
The :term:`not found view` callable is a view callable like any other. The
2323
:term:`view configuration` which causes it to be a "not found" view consists
24-
only of naming the :exc:`pyramid.exceptions.NotFound` class as the
24+
only of naming the :exc:`pyramid.response.HTTPNotFound` class as the
2525
``context`` of the view configuration.
2626

2727
If your application uses :term:`imperative configuration`, you can replace
@@ -31,9 +31,9 @@ method to register an "exception view":
3131
.. code-block:: python
3232
:linenos:
3333
34-
from pyramid.exceptions import NotFound
34+
from pyramid.response import HTTPNotFound
3535
from helloworld.views import notfound_view
36-
config.add_view(notfound_view, context=NotFound)
36+
config.add_view(notfound_view, context=HTTPNotFound)
3737
3838
Replace ``helloworld.views.notfound_view`` with a reference to the
3939
:term:`view callable` you want to use to represent the Not Found view.
@@ -42,33 +42,33 @@ Like any other view, the notfound view must accept at least a ``request``
4242
parameter, or both ``context`` and ``request``. The ``request`` is the
4343
current :term:`request` representing the denied action. The ``context`` (if
4444
used in the call signature) will be the instance of the
45-
:exc:`~pyramid.exceptions.NotFound` exception that caused the view to be
45+
:exc:`~pyramid.response.HTTPNotFound` exception that caused the view to be
4646
called.
4747

4848
Here's some sample code that implements a minimal NotFound view callable:
4949

5050
.. code-block:: python
5151
:linenos:
5252
53-
from pyramid.httpexceptions import HTTPNotFound
53+
from pyramid.response import HTTPNotFound
5454
5555
def notfound_view(request):
5656
return HTTPNotFound()
5757
5858
.. note:: When a NotFound view callable is invoked, it is passed a
59-
:term:`request`. The ``exception`` attribute of the request will
60-
be an instance of the :exc:`~pyramid.exceptions.NotFound`
61-
exception that caused the not found view to be called. The value
62-
of ``request.exception.args[0]`` will be a value explaining why the
63-
not found error was raised. This message will be different when
64-
the ``debug_notfound`` environment setting is true than it is when
65-
it is false.
59+
:term:`request`. The ``exception`` attribute of the request will be an
60+
instance of the :exc:`~pyramid.response.HTTPNotFound` exception that
61+
caused the not found view to be called. The value of
62+
``request.exception.args[0]`` will be a value explaining why the not found
63+
error was raised. This message will be different when the
64+
``debug_notfound`` environment setting is true than it is when it is
65+
false.
6666

6767
.. warning:: When a NotFound view callable accepts an argument list as
6868
described in :ref:`request_and_context_view_definitions`, the ``context``
6969
passed as the first argument to the view callable will be the
70-
:exc:`~pyramid.exceptions.NotFound` exception instance. If available, the
71-
resource context will still be available as ``request.context``.
70+
:exc:`~pyramid.response.HTTPNotFound` exception instance. If available,
71+
the resource context will still be available as ``request.context``.
7272

7373
.. index::
7474
single: forbidden view
@@ -85,7 +85,7 @@ the view which generates it can be overridden as necessary.
8585

8686
The :term:`forbidden view` callable is a view callable like any other. The
8787
:term:`view configuration` which causes it to be a "not found" view consists
88-
only of naming the :exc:`pyramid.exceptions.Forbidden` class as the
88+
only of naming the :exc:`pyramid.response.HTTPForbidden` class as the
8989
``context`` of the view configuration.
9090

9191
You can replace the forbidden view by using the
@@ -96,8 +96,8 @@ view":
9696
:linenos:
9797
9898
from helloworld.views import forbidden_view
99-
from pyramid.exceptions import Forbidden
100-
config.add_view(forbidden_view, context=Forbidden)
99+
from pyramid.response import HTTPForbidden
100+
config.add_view(forbidden_view, context=HTTPForbidden)
101101
102102
Replace ``helloworld.views.forbidden_view`` with a reference to the Python
103103
:term:`view callable` you want to use to represent the Forbidden view.
@@ -121,13 +121,13 @@ Here's some sample code that implements a minimal forbidden view:
121121
return Response('forbidden')
122122
123123
.. note:: When a forbidden view callable is invoked, it is passed a
124-
:term:`request`. The ``exception`` attribute of the request will
125-
be an instance of the :exc:`~pyramid.exceptions.Forbidden`
126-
exception that caused the forbidden view to be called. The value
127-
of ``request.exception.args[0]`` will be a value explaining why the
128-
forbidden was raised. This message will be different when the
129-
``debug_authorization`` environment setting is true than it is when
130-
it is false.
124+
:term:`request`. The ``exception`` attribute of the request will be an
125+
instance of the :exc:`~pyramid.response.HTTPForbidden` exception that
126+
caused the forbidden view to be called. The value of
127+
``request.exception.args[0]`` will be a value explaining why the forbidden
128+
was raised. This message will be different when the
129+
``debug_authorization`` environment setting is true than it is when it is
130+
false.
131131

132132
.. index::
133133
single: request factory

‎docs/narr/renderers.rst

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -73,30 +73,43 @@ When this configuration is added to an application, the
7373
which renders view return values to a :term:`JSON` response serialization.
7474

7575
Other built-in renderers include renderers which use the :term:`Chameleon`
76-
templating language to render a dictionary to a response.
76+
templating language to render a dictionary to a response. Additional
77+
renderers can be added by developers to the system as necessary (see
78+
:ref:`adding_and_overriding_renderers`).
79+
80+
Views which use a renderer can vary non-body response attributes (such as
81+
headers and the HTTP status code) by attaching a property to the
82+
``request.response`` attribute See :ref:`request_response_attr`.
7783

7884
If the :term:`view callable` associated with a :term:`view configuration`
7985
returns a Response object directly (an object with the attributes ``status``,
8086
``headerlist`` and ``app_iter``), any renderer associated with the view
8187
configuration is ignored, and the response is passed back to :app:`Pyramid`
8288
unchanged. For example, if your view callable returns an instance of the
83-
:class:`pyramid.httpexceptions.HTTPFound` class as a response, no renderer
84-
will be employed.
89+
:class:`pyramid.response.HTTPFound` class as a response, no renderer will be
90+
employed.
8591

8692
.. code-block:: python
8793
:linenos:
8894
89-
from pyramid.httpexceptions import HTTPFound
95+
from pyramid.response import HTTPFound
9096
9197
def view(request):
9298
return HTTPFound(location='http://example.com') # any renderer avoided
9399
94-
Views which use a renderer can vary non-body response attributes (such as
95-
headers and the HTTP status code) by attaching a property to the
96-
``request.response`` attribute See :ref:`request_response_attr`.
100+
Likewise for a "plain old response":
101+
102+
.. code-block:: python
103+
:linenos:
104+
105+
from pyramid.response import Response
106+
107+
def view(request):
108+
return Response('OK') # any renderer avoided
97109
98-
Additional renderers can be added by developers to the system as necessary
99-
(see :ref:`adding_and_overriding_renderers`).
110+
Mutations to ``request.response`` in views which return a Response object
111+
like this directly (unless that response *is* ``request.response``) will be
112+
ignored.
100113

101114
.. index::
102115
single: renderers (built-in)

‎docs/narr/router.rst

Lines changed: 25 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -77,40 +77,37 @@ processing?
7777
#. A :class:`~pyramid.events.ContextFound` :term:`event` is
7878
sent to any subscribers.
7979

80-
#. :app:`Pyramid` looks up a :term:`view` callable using the
81-
context, the request, and the view name. If a view callable
82-
doesn't exist for this combination of objects (based on the type of
83-
the context, the type of the request, and the value of the view
84-
name, and any :term:`predicate` attributes applied to the view
85-
configuration), :app:`Pyramid` raises a
86-
:class:`~pyramid.exceptions.NotFound` exception, which is meant
87-
to be caught by a surrounding exception handler.
80+
#. :app:`Pyramid` looks up a :term:`view` callable using the context, the
81+
request, and the view name. If a view callable doesn't exist for this
82+
combination of objects (based on the type of the context, the type of the
83+
request, and the value of the view name, and any :term:`predicate`
84+
attributes applied to the view configuration), :app:`Pyramid` raises a
85+
:class:`~pyramid.response.HTTPNotFound` exception, which is meant to be
86+
caught by a surrounding exception handler.
8887

8988
#. If a view callable was found, :app:`Pyramid` attempts to call
9089
the view function.
9190

92-
#. If an :term:`authorization policy` is in use, and the view was
93-
protected by a :term:`permission`, :app:`Pyramid` passes the
94-
context, the request, and the view_name to a function which
95-
determines whether the view being asked for can be executed by the
96-
requesting user, based on credential information in the request and
97-
security information attached to the context. If it returns
98-
``True``, :app:`Pyramid` calls the view callable to obtain a
99-
response. If it returns ``False``, it raises a
100-
:class:`~pyramid.exceptions.Forbidden` exception, which is meant
101-
to be called by a surrounding exception handler.
91+
#. If an :term:`authorization policy` is in use, and the view was protected
92+
by a :term:`permission`, :app:`Pyramid` passes the context, the request,
93+
and the view_name to a function which determines whether the view being
94+
asked for can be executed by the requesting user, based on credential
95+
information in the request and security information attached to the
96+
context. If it returns ``True``, :app:`Pyramid` calls the view callable
97+
to obtain a response. If it returns ``False``, it raises a
98+
:class:`~pyramid.response.HTTPForbidden` exception, which is meant to be
99< 10000 span class="diff-text-marker">+
called by a surrounding exception handler.
102100

103101
#. If any exception was raised within a :term:`root factory`, by
104-
:term:`traversal`, by a :term:`view callable` or by
105-
:app:`Pyramid` itself (such as when it raises
106-
:class:`~pyramid.exceptions.NotFound` or
107-
:class:`~pyramid.exceptions.Forbidden`), the router catches the
108-
exception, and attaches it to the request as the ``exception``
109-
attribute. It then attempts to find a :term:`exception view` for
110-
the exception that was caught. If it finds an exception view
111-
callable, that callable is called, and is presumed to generate a
112-
response. If an :term:`exception view` that matches the exception
113-
cannot be found, the exception is reraised.
102+
:term:`traversal`, by a :term:`view callable` or by :app:`Pyramid` itself
103+
(such as when it raises :class:`~pyramid.response.HTTPNotFound` or
104+
:class:`~pyramid.response.HTTPForbidden`), the router catches the
105+
exception, and attaches it to the request as the ``exception`` attribute.
106+
It then attempts to find a :term:`exception view` for the exception that
107+
was caught. If it finds an exception view callable, that callable is
108+
called, and is presumed to generate a response. If an :term:`exception
109+
view` that matches the exception cannot be found, the exception is
110+
reraised.
114111

115112
#. The following steps occur only when a :term:`response` could be
116113
successfully generated by a normal :term:`view callable` or an

‎docs/narr/testing.rst

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -191,11 +191,11 @@ function.
191191
:linenos:
192192
193193
from pyramid.security import has_permission
194-
from pyramid.exceptions import Forbidden
194+
from pyramid.response import HTTPForbidden
195195
196196
def view_fn(request):
197197
if not has_permission('edit', request.context, request):
198-
raise Forbidden
198+
raise HTTPForbidden
199199
return {'greeting':'hello'}
200200
201201
Without doing anything special during a unit test, the call to
@@ -207,7 +207,7 @@ application registry is not created and populated (e.g. by initializing the
207207
configurator with an authorization policy), like when you invoke application
208208
code via a unit test, :app:`Pyramid` API functions will tend to either fail
209209
or return default results. So how do you test the branch of the code in this
210-
view function that raises :exc:`Forbidden`?
210+
view function that raises :exc:`HTTPForbidden`?
211211

212212
The testing API provided by :app:`Pyramid` allows you to simulate various
213213
application registry registrations for use under a unit testing framework
@@ -230,16 +230,15 @@ without needing to invoke the actual application configuration implied by its
230230
testing.tearDown()
231231
232232
def test_view_fn_forbidden(self):
233-
from pyramid.exceptions import Forbidden
233+
from pyramid.response import HTTPForbidden
234234
from my.package import view_fn
235235
self.config.testing_securitypolicy(userid='hank',
236236
permissive=False)
237237
request = testing.DummyRequest()
238238
request.context = testing.DummyResource()
239-
self.assertRaises(Forbidden, view_fn, request)
239+
self.assertRaises(HTTPForbidden, view_fn, request)
240240
241241
def test_view_fn_allowed(self):
242-
from pyramid.exceptions import Forbidden
243242
from my.package import view_fn
244243
self.config.testing_securitypolicy(userid='hank',
245244
permissive=True)
@@ -265,7 +264,7 @@ We call the function being tested with the manufactured request. When the
265264
function is called, :func:`pyramid.security.has_permission` will call the
266265
"dummy" authentication policy we've registered through
267266
:meth:`~pyramid.config.Configuration.testing_securitypolicy`, which denies
268-
access. We check that the view function raises a :exc:`Forbidden` error.
267+
access. We check that the view function raises a :exc:`HTTPForbidden` error.
269268

270269
The second test method, named ``test_view_fn_allowed`` tests the alternate
271270
case, where the authentication policy allows access. Notice that we pass

‎docs/narr/urldispatch.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -917,7 +917,7 @@ the application's startup configuration, adding the following stanza:
917917
:linenos:
918918
919919
config.add_view('pyramid.view.append_slash_notfound_view',
920-
context='pyramid.exceptions.NotFound')
920+
context='pyramid.response.HTTPNotFound')
921921
922922
See :ref:`view_module` and :ref:`changing_the_notfound_view` for more
923923
information about the slash-appending not found view and for a more general
@@ -945,14 +945,14 @@ view as the first argument to its constructor. For instance:
945945
.. code-block:: python
946946
:linenos:
947947
948-
from pyramid.exceptions import NotFound
948+
from pyramid.response import HTTPNotFound
949949
from pyramid.view import AppendSlashNotFoundViewFactory
950950
951951
def notfound_view(context, request):
952952
return HTTPNotFound('It aint there, stop trying!')
953953
954954
custom_append_slash = AppendSlashNotFoundViewFactory(notfound_view)
955-
config.add_view(custom_append_slash, context=NotFound)
955+
config.add_view(custom_append_slash, context=HTTPNotFound)
956956
957957
The ``notfound_view`` supplied must adhere to the two-argument view callable
958958
calling convention of ``(context, request)`` (``context`` will be the

0 commit comments

Comments
 (0)
0