RedHatTraining/pyramid.git

Added the pyramid.* settings to the settings dict.

Michael Merickel

2011-07-30 e1b25974a4dcc9eb9ceab70ec2276043de775f82

commit \| author \| age
9a66aa	1	Next release
CM	2	============
	3
	4	Features
	5	--------
	6
1f901a	7	- Added a decorator-based way to configure a response adapter:
CM	8	``pyramid.response.response_adapter``. This decorator has the same use as
	9	``pyramid.config.Configurator.add_response_adapter`` but it's declarative.
	10
9a66aa	11	- The ``pyramid.events.BeforeRender`` event now has an attribute named
CM	12	``rendering_val``. This can be used to introspect the value returned by a
	13	view in a BeforeRender subscriber.
	14
f91e0c	15	- New configurator directive:
47525f	16	``pyramid.config.Configurator.add_request_handler``. This directive adds
CM	17	a request handler factory.
af2323	18
47525f	19	A request handler factory is used to wrap the Pyramid router's primary
CM	20	request handling function. This is a feature may be used by framework
	21	extensions, to provide, for example, view timing support and as a
	22	convenient place to hang bookkeeping code that examines exceptions before
	23	they are returned to the server.
af2323	24
47525f	25	A request handler factory (passed as ``handler_factory``) must be a
CM	26	callable which accepts two arguments: ``handler`` and ``registry``.
	27	``handler`` will be the request handler being wrapped. ``registry`` will
	28	be the Pyramid application registry represented by this Configurator. A
	29	request handler factory must return a request handler when it is called.
af2323	30
47525f	31	A request handler accepts a request object and returns a response object.
af2323	32
47525f	33	Here's an example of creating both a handler factory and a handler, and
CM	34	registering the handler factory:
af2323	35
47525f	36	.. code-block:: python
af2323	37
CM	38	import time
	39
	40	def timing_handler_factory(handler, registry):
	41	if registry.settings['do_timing']:
	42	# if timing support is enabled, return a wrapper
	43	def timing_handler(request):
	44	start = time.time()
	45	try:
	46	response = handler(request)
	47	finally:
	48	end = time.time()
	49	print: 'The request took %s seconds' % (end - start)
	50	return response
	51	return timing_handler
	52	# if timing support is not enabled, return the original handler
	53	return handler
	54
	55	config.add_request_handler(timing_handler_factory, 'timing')
	56
47525f	57	The ``request`` argument to the handler will be the request created by
CM	58	Pyramid's router when it receives a WSGI request.
af2323	59
47525f	60	If more than one request handler factory is registered into a single
CM	61	configuration, the request handlers will be chained together. The first
	62	request handler factory added (in code execution order) will be called with
	63	the default Pyramid request handler, the second handler factory added will
	64	be called with the result of the first handler factory, ad infinitum. The
	65	Pyramid router will use the outermost wrapper in this chain (which is a bit
	66	like a WSGI middleware "pipeline") as its handler function.
af2323	67
47525f	68	The ``name`` argument to this function is required. The name is used as a
CM	69	key for conflict detection. No two request handler factories may share the
	70	same name in the same configuration (unless automatic_conflict_resolution
	71	is able to resolve the conflict or this is an autocommitting configurator).
b72379	72
3a8054	73	- The Pyramid debug logger now uses the standard logging configuration
CM	74	(usually set up by Paste as part of startup). This means that output from
	75	e.g. ``debug_notfound``, ``debug_authorization``, etc. will go to the
	76	normal logging channels. The logger name of the debug logger will be the
	77	package name of the caller of the Configurator's constructor.
	78
	79	Backwards Incompatibilities
	80	---------------------------
	81
	82	- If a string is passed as the ``debug_logger`` parameter to a Configurator,
	83	that string is considered to be the name of a global Python logger rather
	84	than a dotted name to an instance of a logger.
	85
8c0344	86	1.1 (2011-07-22)
CM	87	================
ead3c7	88
aa2fe1	89	Features
CM	90	--------
	91
	92	- Added the ``pyramid.renderers.null_renderer`` object as an API. The null
	93	renderer is an object that can be used in advanced integration cases as
	94	input to the view configuration ``renderer=`` argument. When the null
	95	renderer is used as a view renderer argument, Pyramid avoids converting the
	96	view callable result into a Response object. This is useful if you want to
	97	reuse the view configuration and lookup machinery outside the context of
	98	its use by the Pyramid router. This feature was added for consumption by
	99	the ``pyramid_rpc`` package, which uses view configuration and lookup
	100	outside the context of a router in exactly this way. ``pyramid_rpc`` has
	101	been broken under 1.1 since 1.1b1; adding it allows us to make it work
	102	again.
	103
39e88a	104	- Change all scaffolding templates that point to docs.pylonsproject.org to
CM	105	use ``/projects/pyramid/current`` rather than ``/projects/pyramid/dev``.
	106
e7cb93	107	Internals
CM	108	---------
	109
	110	- Remove ``compat`` code that served only the purpose of providing backwards
	111	compatibility with Python 2.4.
	112
73c0ae	113	- Add a deprecation warning for non-API function
CM	114	``pyramid.renderers.renderer_from_name`` which has seen use in the wild.
	115
	116	- Add a ``clone`` method to ``pyramid.renderers.RendererHelper`` for use by
	117	the ``pyramid.view.view_config`` decorator.
	118
ead3c7	119	Documentation
CM	120	-------------
	121
	122	- Fixed two typos in wiki2 (SQLA + URL Dispatch) tutorial.
	123
8cb682	124	- Reordered chapters in narrative section for better new user friendliness.
CM	125
	126	- Added more indexing markers to sections in documentation.
	127
40c643	128	1.1b4 (2011-07-18)
CM	129	==================
5fb458	130
CM	131	Documentation
	132	-------------
	133
	134	- Added a section entitled "Writing a Script" to the "Command-Line Pyramid"
	135	chapter.
	136
f06ce6	137	Backwards Incompatibilities
CM	138	---------------------------
	139
	140	- We added the ``pyramid.scripting.make_request`` API too hastily in 1.1b3.
	141	It has been removed. Sorry for any inconvenience. Use the
	142	``pyramid.request.Request.blank`` API instead.
	143
95df42	144	Features
CM	145	--------
	146
af0560	147	- The ``paster pshell``, ``paster pviews``, and ``paster proutes`` commands
CM	148	each now under the hood uses ``pyramid.paster.bootstrap``, which makes it
	149	possible to supply an ``.ini`` file without naming the "right" section in
	150	the file that points at the actual Pyramid application. Instead, you can
	151	generally just run ``paster {pshell\|proutes\|pviews} development.ini`` and
	152	it will do mostly the right thing.
95df42	153
4b3ba9	154	Bug Fixes
CM	155	---------
	156
	157	- Omit custom environ variables when rendering a custom exception template in
	158	``pyramid.httpexceptions.WSGIHTTPException._set_default_attrs``;
	159	stringifying thse may trigger code that should not be executed; see
	160	https://github.com/Pylons/pyramid/issues/239
	161
999d44	162	1.1b3 (2011-07-15)
CM	163	==================
2ad827	164
CM	165	Features
	166	--------
	167
	168	- Fix corner case to ease semifunctional testing of views: create a new
	169	rendererinfo to clear out old registry on a rescan. See
	170	https://github.com/Pylons/pyramid/pull/234.
	171
56d0fe	172	- New API class: ``pyramid.static.static_view``. This supersedes the
100a57	173	deprecated ``pyramid.view.static`` class. ``pyramid.static.static_view``
CM	174	by default serves up documents as the result of the request's
	175	``path_info``, attribute rather than it's ``subpath`` attribute (the
	176	inverse was true of ``pyramid.view.static``, and still is).
	177	``pyramid.static.static_view`` exposes a ``use_subpath`` flag for use when
10408c	178	you want the static view to behave like the older deprecated version.
56d0fe	179
c515d7	180	- A new API function ``pyramid.paster.bootstrap`` has been added to make
CM	181	writing scripts that bootstrap a Pyramid environment easier, e.g.::
	182
	183	from pyramid.paster import bootstrap
	184	info = bootstrap('/path/to/my/development.ini')
	185	request = info['request']
	186	print request.route_url('myroute')
	187
	188	- A new API function ``pyramid.scripting.prepare`` has been added. It is a
	189	lower-level analogue of ``pyramid.paster.boostrap`` that accepts a request
	190	and a registry instead of a config file argument, and is used for the same
	191	purpose::
	192
	193	from pyramid.scripting import prepare
	194	info = prepare(registry=myregistry)
	195	request = info['request']
	196	print request.route_url('myroute')
	197
	198	- A new API function ``pyramid.scripting.make_request`` has been added. The
	199	resulting request will have a ``registry`` attribute. It is meant to be
	200	used in conjunction with ``pyramid.scripting.prepare`` and/or
	201	``pyramid.paster.bootstrap`` (both of which accept a request as an
	202	argument)::
	203
	204	from pyramid.scripting import make_request
	205	request = make_request('/')
	206
	207	- New API attribute ``pyramid.config.global_registries`` is an iterable
	208	object that contains references to every Pyramid registry loaded into the
	209	current process via ``pyramid.config.Configurator.make_app``. It also has
	210	a ``last`` attribute containing the last registry loaded. This is used by
	211	the scripting machinery, and is available for introspection.
	212
56d0fe	213	Deprecations
CM	214	------------
	215
	216	- The ``pyramid.view.static`` class has been deprecated in favor of the newer
	217	``pyramid.static.static_view`` class. A deprecation warning is raised when
	218	it is used. You should replace it with a reference to
	219	``pyramid.static.static_view`` with the ``use_subpath=True`` argument.
	220
5b5cd6	221	Bug Fixes
CM	222	---------
	223
	224	- Without a mo-file loaded for the combination of domain/locale,
	225	``pyramid.i18n.Localizer.pluralize`` run using that domain/locale
acc2d3	226	combination raised an inscrutable "translations object has no attr
CM	227	'plural'" error. Now, instead it "works" (it uses a germanic pluralization
	228	by default). It's nonsensical to try to pluralize something without
	229	translations for that locale/domain available, but this behavior matches
	230	the behavior of ``pyramid.i18n.Localizer.translate`` so it's at least
	231	consistent; see https://github.com/Pylons/pyramid/issues/235.
5b5cd6	232
d4ccb8	233	1.1b2 (2011-07-13)
CM	234	==================
82efa4	235
e573d4	236	Features
CM	237	--------
	238
	239	- New environment setting ``PYRAMID_PREVENT_HTTP_CACHE`` and new
	240	configuration file value ``prevent_http_cache``. These are synomymous and
	241	allow you to prevent HTTP cache headers from being set by Pyramid's
	242	``http_cache`` machinery globally in a process. see the "Influencing HTTP
	243	Caching" section of the "View Configuration" narrative chapter and the
	244	detailed documentation for this setting in the "Environment Variables and
	245	Configuration Settings" narrative chapter.
	246
82efa4	247	Behavior Changes
CM	248	----------------
	249
	250	- Previously, If a ``BeforeRender`` event subscriber added a value via the
	251	``__setitem__`` or ``update`` methods of the event object with a key that
	252	already existed in the renderer globals dictionary, a ``KeyError`` was
	253	raised. With the deprecation of the "add_renderer_globals" feature of the
	254	configurator, there was no way to override an existing value in the
	255	renderer globals dictionary that already existed. Now, the event object
	256	will overwrite an older value that is already in the globals dictionary
	257	when its ``__setitem__`` or ``update`` is called (as well as the new
	258	``setdefault`` method), just like a plain old dictionary. As a result, for
	259	maximum interoperability with other third-party subscribers, if you write
	260	an event subscriber meant to be used as a BeforeRender subscriber, your
	261	subscriber code will now need to (using ``.get`` or ``__contains__`` of the
	262	event object) ensure no value already exists in the renderer globals
	263	dictionary before setting an overriding value.
	264
94ab24	265	Bug Fixes
CM	266	---------
	267
	268	- The ``Configurator.add_route`` method allowed two routes with the same
	269	route to be added without an intermediate ``config.commit()``. If you now
	270	receive a ``ConfigurationError`` at startup time that appears to be
	271	``add_route`` related, you'll need to either a) ensure that all of your
	272	route names are unique or b) call ``config.commit()`` before adding a
	273	second route with the name of a previously added name or c) use a
	274	Configurator that works in ``autocommit`` mode.
	275
aec6b2	276	- The ``pyramid_routesalchemy`` and ``pyramid_alchemy`` scaffolds
CM	277	inappropriately used ``DBSession.rollback()`` instead of
	278	``transaction.abort()`` in one place.
	279
d05117	280	- We now clear ``request.response`` before we invoke an exception view; an
CM	281	exception view will be working with a request.response that has not been
	282	touched by any code prior to the exception.
	283
873d9b	284	- Views associated with routes with spaces in the route name may not have
CM	285	been looked up correctly when using Pyramid with ``zope.interface`` 3.6.4
d4ccb8	286	and better. See https://github.com/Pylons/pyramid/issues/232.
873d9b	287
aec6b2	288	Documentation
CM	289	-------------
	290
	291	- Wiki2 (SQLAlchemy + URL Dispatch) tutorial ``models.initialize_sql`` didn't
	292	match the ``pyramid_routesalchemy`` scaffold function of the same name; it
	293	didn't get synchronized when it was changed in the scaffold.
	294
e573d4	295	- New documentation section in View Configuration narrative chapter:
CM	296	"Influencing HTTP Caching".
	297
a36fdb	298	1.1b1 (2011-07-10)
CM	299	==================
0fa199	300
CM	301	Features
	302	--------
	303
756500	304	- It is now possible to invoke ``paster pshell`` even if the paste ini file
CM	305	section name pointed to in its argument is not actually a Pyramid WSGI
	306	application. The shell will work in a degraded mode, and will warn the
	307	user. See "The Interactive Shell" in the "Creating a Pyramid Project"
	308	narrative documentation section.
	309
	310	- ``paster pshell`` now offers more built-in global variables by default
	311	(including ``app`` and ``settings``). See "The Interactive Shell" in the
	312	"Creating a Pyramid Project" narrative documentation section.
	313
	314	- It is now possible to add a ``[pshell]`` section to your application's .ini
	315	configuration file, which influences the global names available to a pshell
	316	session. See "Extending the Shell" in the "Creating a Pyramid Project"
	317	narrative documentation chapter.
	318
fca1ef	319	- The ``config.scan`` method has grown a ``**kw`` argument. ``kw`` argument
CM	320	represents a set of keyword arguments to pass to the Venusian ``Scanner``
	321	object created by Pyramid. (See the Venusian documentation for more
	322	information about ``Scanner``).
	323
6a0602	324	- New request property: ``json_body``. This property will return the
CM	325	JSON-decoded variant of the request body. If the request body is not
	326	well-formed JSON, this property will raise an exception.
b78eff	327
0fa199	328	- A new value ``http_cache`` can be used as a view configuration
CM	329	parameter.
	330
	331	When you supply an ``http_cache`` value to a view configuration, the
	332	``Expires`` and ``Cache-Control`` headers of a response generated by the
	333	associated view callable are modified. The value for ``http_cache`` may be
	334	one of the following:
	335
	336	- A nonzero integer. If it's a nonzero integer, it's treated as a number
	337	of seconds. This number of seconds will be used to compute the
	338	``Expires`` header and the ``Cache-Control: max-age`` parameter of
	339	responses to requests which call this view. For example:
	340	``http_cache=3600`` instructs the requesting browser to 'cache this
	341	response for an hour, please'.
	342
	343	- A ``datetime.timedelta`` instance. If it's a ``datetime.timedelta``
	344	instance, it will be converted into a number of seconds, and that number
	345	of seconds will be used to compute the ``Expires`` header and the
	346	``Cache-Control: max-age`` parameter of responses to requests which call
	347	this view. For example: ``http_cache=datetime.timedelta(days=1)``
	348	instructs the requesting browser to 'cache this response for a day,
	349	please'.
	350
	351	- Zero (``0``). If the value is zero, the ``Cache-Control`` and
	352	``Expires`` headers present in all responses from this view will be
	353	composed such that client browser cache (and any intermediate caches) are
	354	instructed to never cache the response.
	355
	356	- A two-tuple. If it's a two tuple (e.g. ``http_cache=(1,
	357	{'public':True})``), the first value in the tuple may be a nonzero
	358	integer or a ``datetime.timedelta`` instance; in either case this value
	359	will be used as the number of seconds to cache the response. The second
	360	value in the tuple must be a dictionary. The values present in the
	361	dictionary will be used as input to the ``Cache-Control`` response
	362	header. For example: ``http_cache=(3600, {'public':True})`` means 'cache
	363	for an hour, and add ``public`` to the Cache-Control header of the
	364	response'. All keys and values supported by the
	365	``webob.cachecontrol.CacheControl`` interface may be added to the
	366	dictionary. Supplying ``{'public':True}`` is equivalent to calling
	367	``response.cache_control.public = True``.
	368
	369	Providing a non-tuple value as ``http_cache`` is equivalent to calling
	370	``response.cache_expires(value)`` within your view's body.
	371
	372	Providing a two-tuple value as ``http_cache`` is equivalent to calling
	373	``response.cache_expires(value[0], **value[1])`` within your view's body.
	374
	375	If you wish to avoid influencing, the ``Expires`` header, and instead wish
	376	to only influence ``Cache-Control`` headers, pass a tuple as ``http_cache``
	377	with the first element of ``None``, e.g.: ``(None, {'public':True})``.
	378
b44aab	379	Bug Fixes
CM	380	---------
	381
	382	- Framework wrappers of the original view (such as http_cached and so on)
	383	relied on being able to trust that the response they were receiving was an
	384	IResponse. It wasn't always, because the response was resolved by the
	385	router instead of early in the view wrapping process. This has been fixed.
	386
6a0602	387	Documentation
CM	388	-------------
	389
	390	- Added a section in the "Webob" chapter named "Dealing With A JSON-Encoded
	391	Request Body" (usage of ``request.json_body``).
	392
756500	393	Behavior Changes
CM	394	----------------
	395
	396	- The ``paster pshell``, ``paster proutes``, and ``paster pviews`` commands
	397	now take a single argument in the form ``/path/to/config.ini#sectionname``
	398	rather than the previous 2-argument spelling ``/path/to/config.ini
	399	sectionname``. ``#sectionname`` may be omitted, in which case ``#main`` is
	400	assumed.
	401
b9c0e7	402	1.1a4 (2011-07-01)
CM	403	==================
9395f0	404
CM	405	Bug Fixes
	406	---------
	407
	408	- ``pyramid.testing.DummyRequest`` now raises deprecation warnings when
	409	attributes deprecated for ``pyramid.request.Request`` are accessed (like
	410	``response_content_type``). This is for the benefit of folks running unit
	411	tests which use DummyRequest instead of a "real" request, so they know
	412	things are deprecated without necessarily needing a functional test suite.
	413
2ea5c1	414	- The ``pyramid.events.subscriber`` directive behaved contrary to the
CM	415	documentation when passed more than one interface object to its
	416	constructor. For example, when the following listener was registered::
	417
	418	@subscriber(IFoo, IBar)
	419	def expects_ifoo_events_and_ibar_events(event):
	420	print event
	421
	422	The Events chapter docs claimed that the listener would be registered and
	423	listening for both ``IFoo`` and ``IBar`` events. Instead, it registered an
	424	"object event" subscriber which would only be called if an IObjectEvent was
	425	emitted where the object interface was ``IFoo`` and the event interface was
	426	``IBar``.
	427
	428	The behavior now matches the documentation. If you were relying on the
	429	buggy behavior of the 1.0 ``subscriber`` directive in order to register an
	430	object event subscriber, you must now pass a sequence to indicate you'd
8519c9	431	like to register a subscriber for an object event. e.g.::
2ea5c1	432
CM	433	@subscriber([IFoo, IBar])
	434	def expects_object_event(object, event):
	435	print object, event
	436
c1f3d0	437	Features
CM	438	--------
	439
	440	- Add JSONP renderer (see "JSONP renderer" in the Renderers chapter of the
	441	documentation).
	442
b7f33b	443	Deprecations
CM	444	------------
	445
	446	- Deprecated the ``set_renderer_globals_factory`` method of the Configurator
	447	and the ``renderer_globals`` Configurator constructor parameter.
	448
05a1b4	449	Documentation
CM	450	-------------
	451
6c9959	452	- The Wiki and Wiki2 tutorial "Tests" chapters each had two bugs: neither did
CM	453	told the user to depend on WebTest, and 2 tests failed in each as the
	454	result of changes to Pyramid itself. These issues have been fixed.
05a1b4	455
e21ed8	456	- Move 1.0.X CHANGES.txt entries to HISTORY.txt.
CM	457
1ba6fe	458	1.1a3 (2011-06-26)
CM	459	==================
05fd08	460
8bd6cf	461	Features
CM	462	--------
	463
	464	- Added ``mako.preprocessor`` config file parameter; allows for a Mako
	465	preprocessor to be specified as a Python callable or Python dotted name.
	466	See https://github.com/Pylons/pyramid/pull/183 for rationale.
	467
05fd08	468	Bug fixes
CM	469	---------
	470
	471	- Pyramid would raise an AttributeError in the Configurator when attempting
	472	to set a ``__text__`` attribute on a custom predicate that was actually a
	473	classmethod. See https://github.com/Pylons/pyramid/pull/217 .
	474
d8c55c	475	- Accessing or setting deprecated response_* attrs on request
CM	476	(e.g. ``response_content_type``) now issues a deprecation warning at access
	477	time rather than at rendering time.
05fd08	478
cc85e7	479	1.1a2 (2011-06-22)
CM	480	==================
c724f0	481
d74d53	482	Bug Fixes
CM	483	---------
	484
	485	- 1.1a1 broke Akhet by not providing a backwards compatibility import shim
	486	for ``pyramid.paster.PyramidTemplate``. Now one has been added, although a
cc85e7	487	deprecation warning is emitted when Akhet imports it.
d74d53	488
6ed33e	489	- If multiple specs were provided in a single call to
CM	490	``config.add_translation_dirs``, the directories were inserted into the
	491	beginning of the directory list in the wrong order: they were inserted in
	492	the reverse of the order they were provided in the ``*specs`` list (items
4f11dc	493	later in the list were added before ones earlier in the list). This is now
CM	494	fixed.
6ed33e	495
c724f0	496	Backwards Incompatibilities
CM	497	---------------------------
	498
	499	- The pyramid Router attempted to set a value into the key
	500	``environ['repoze.bfg.message']`` when it caught a view-related exception
cc85e7	501	for backwards compatibility with applications written for ``repoze.bfg``
CM	502	during error handling. It did this by using code that looked like so::
c724f0	503
CM	504	# "why" is an exception object
	505	try:
	506	msg = why[0]
	507	except:
	508	msg = ''
	509
	510	environ['repoze.bfg.message'] = msg
	511
	512	Use of the value ``environ['repoze.bfg.message']`` was docs-deprecated in
	513	Pyramid 1.0. Our standing policy is to not remove features after a
	514	deprecation for two full major releases, so this code was originally slated
	515	to be removed in Pyramid 1.2. However, computing the
	516	``repoze.bfg.message`` value was the source of at least one bug found in
	517	the wild (https://github.com/Pylons/pyramid/issues/199), and there isn't a
	518	foolproof way to both preserve backwards compatibility and to fix the bug.
	519	Therefore, the code which sets the value has been removed in this release.
	520	Code in exception views which relies on this value's presence in the
	521	environment should now use the ``exception`` attribute of the request
	522	(e.g. ``request.exception[0]``) to retrieve the message instead of relying
	523	on ``request.environ['repoze.bfg.message']``.
	524
83549e	525	1.1a1 (2011-06-20)
CM	526	==================
959523	527
8027ad	528	Documentation
JD	529	-------------
	530
af71c2	531	- The term "template" used to refer to both "paster templates" and "rendered
CM	532	templates" (templates created by a rendering engine. i.e. Mako, Chameleon,
	533	Jinja, etc.). "Paster templates" will now be refered to as "scaffolds",
	534	whereas the name for "rendered templates" will remain as "templates."
8027ad	535
88f967	536	- The ``wiki`` (ZODB+Traversal) tutorial was updated slightly.
CM	537
	538	- The ``wiki2`` (SQLA+URL Dispatch) tutorial was updated slightly.
	539
d2973d	540	- Make ``pyramid.interfaces.IAuthenticationPolicy`` and
CM	541	``pyramid.interfaces.IAuthorizationPolicy`` public interfaces, and refer to
	542	them within the ``pyramid.authentication`` and ``pyramid.authorization``
	543	API docs.
	544
	545	- Render the function definitions for each exposed interface in
	546	``pyramid.interfaces``.
	547
cae85d	548	- Add missing docs reference to
CM	549	``pyramid.config.Configurator.set_view_mapper`` and refer to it within
	550	Hooks chapter section named "Using a View Mapper".
	551
f6799b	552	- Added section to the "Environment Variables and ``.ini`` File Settings"
CM	553	chapter in the narrative documentation section entitled "Adding a Custom
	554	Setting".
	555
2a1c3f	556	- Added documentation for a "multidict" (e.g. the API of ``request.POST``) as
CM	557	interface API documentation.
	558
e725cf	559	- Added a section to the "URL Dispatch" narrative chapter regarding the new
CM	560	"static" route feature.
	561
2ce652	562	- Added "What's New in Pyramid 1.1" to HTML rendering of documentation.
CM	563
0ca4bb	564	- Added API docs for ``pyramid.authentication.SessionAuthenticationPolicy``.
CM	565
f8f08b	566	- Added API docs for ``pyramid.httpexceptions.exception_response``.
1ffb8e	567
CM	568	- Added "HTTP Exceptions" section to Views narrative chapter including a
f8f08b	569	description of ``pyramid.httpexceptions.exception_response``.
1ffb8e	570
fcbd7b	571	Features
CM	572	--------
4d9260	573
f3e62c	574	- Add support for language fallbacks: when trying to translate for a
WA	575	specific territory (such as ``en_GB``) fall back to translations
	576	for the language (ie ``en``). This brings the translation behaviour in line
	577	with GNU gettext and fixes partially translated texts when using C
	578	extensions.
	579
0ca4bb	580	- New authentication policy:
CM	581	``pyramid.authentication.SessionAuthenticationPolicy``, which uses a session
	582	to store credentials.
	583
4d9260	584	- Accessing the ``response`` attribute of a ``pyramid.request.Request``
CM	585	object (e.g. ``request.response`` within a view) now produces a new
	586	``pyramid.response.Response`` object. This feature is meant to be used
	587	mainly when a view configured with a renderer needs to set response
db51c0	588	attributes: all renderers will use the Response object implied by
CM	589	``request.response`` as the response object returned to the router.
	590
	591	``request.response`` can also be used by code in a view that does not use a
	592	renderer, however the response object that is produced by
	593	``request.response`` must be returned when a renderer is not in play (it is
	594	not a "global" response).
fcbd7b	595
CM	596	- Integers and longs passed as ``elements`` to ``pyramid.url.resource_url``
	597	or ``pyramid.request.Request.resource_url`` e.g. ``resource_url(context,
	598	request, 1, 2)`` (``1`` and ``2`` are the ``elements``) will now be
	599	converted implicitly to strings in the result. Previously passing integers
	600	or longs as elements would cause a TypeError.
	601
296ee2	602	- ``pyramid_alchemy`` paster template now uses ``query.get`` rather than
CM	603	``query.filter_by`` to take better advantage of identity map caching.
	604
	605	- ``pyramid_alchemy`` paster template now has unit tests.
	606
2242e6	607	- Added ``pyramid.i18n.make_localizer`` API (broken out from
CM	608	``get_localizer`` guts).
	609
ba2ac1	610	- An exception raised by a NewRequest event subscriber can now be caught by
CM	611	an exception view.
	612
b32552	613	- It is now possible to get information about why Pyramid raised a Forbidden
CM	614	exception from within an exception view. The ``ACLDenied`` object returned
	615	by the ``permits`` method of each stock authorization policy
	616	(``pyramid.interfaces.IAuthorizationPolicy.permits``) is now attached to
	617	the Forbidden exception as its ``result`` attribute. Therefore, if you've
	618	created a Forbidden exception view, you can see the ACE, ACL, permission,
	619	and principals involved in the request as
	620	eg. ``context.result.permission``, ``context.result.acl``, etc within the
	621	logic of the Forbidden exception view.
	622
474df5	623	- Don't explicitly prevent the ``timeout`` from being lower than the
CM	624	``reissue_time`` when setting up an ``AuthTktAuthenticationPolicy``
	625	(previously such a configuration would raise a ``ValueError``, now it's
	626	allowed, although typically nonsensical). Allowing the nonsensical
	627	configuration made the code more understandable and required fewer tests.
	628
99a32e	629	- A new paster command named ``paster pviews`` was added. This command
CM	630	prints a summary of potentially matching views for a given path. See the
	631	section entitled "Displaying Matching Views for a Given URL" in the "View
	632	Configuration" chapter of the narrative documentation for more information.
	633
e725cf	634	- The ``add_route`` method of the Configurator now accepts a ``static``
CM	635	argument. If this argument is ``True``, the added route will never be
	636	considered for matching when a request is handled. Instead, it will only
	637	be useful for URL generation via ``route_url`` and ``route_path``. See the
	638	section entitled "Static Routes" in the URL Dispatch narrative chapter for
	639	more information.
	640
966b5c	641	- A default exception view for the context
99edc5	642	``pyramid.interfaces.IExceptionResponse`` is now registered by default.
CM	643	This means that an instance of any exception response class imported from
	644	``pyramid.httpexceptions`` (such as ``HTTPFound``) can now be raised from
	645	within view code; when raised, this exception view will render the
	646	exception to a response.
1ffb8e	647
f8f08b	648	- A function named ``pyramid.httpexceptions.exception_response`` is a
CM	649	shortcut that can be used to create HTTP exception response objects using
	650	an HTTP integer status code.
1ffb8e	651
CM	652	- The Configurator now accepts an additional keyword argument named
966b5c	653	``exceptionresponse_view``. By default, this argument is populated with a
CM	654	default exception view function that will be used when a response is raised
	655	as an exception. When ``None`` is passed for this value, an exception view
	656	for responses will not be registered. Passing ``None`` returns the
	657	behavior of raising an HTTP exception to that of Pyramid 1.0 (the exception
	658	will propagate to middleware and to the WSGI server).
	659
	660	- The ``pyramid.request.Request`` class now has a ``ResponseClass`` interface
	661	which points at ``pyramid.response.Response``.
	662
8cbbd9	663	- The ``pyramid.response.Response`` class now has a ``RequestClass``
CM	664	interface which points at ``pyramid.request.Request``.
1ffb8e	665
d868ff	666	- It is now possible to return an arbitrary object from a Pyramid view
CM	667	callable even if a renderer is not used, as long as a suitable adapter to
	668	``pyramid.interfaces.IResponse`` is registered for the type of the returned
1a6fc7	669	object by using the new
CM	670	``pyramid.config.Configurator.add_response_adapter`` API. See the section
	671	in the Hooks chapter of the documentation entitled "Changing How Pyramid
	672	Treats View Responses".
df15ed	673
99edc5	674	- The Pyramid router will now, by default, call the ``__call__`` method of
CM	675	WebOb response objects when returning a WSGI response. This means that,
	676	among other things, the ``conditional_response`` feature of WebOb response
	677	objects will now behave properly.
df15ed	678
920990	679	- New method named ``pyramid.request.Request.is_response``. This method
CM	680	should be used instead of the ``pyramid.view.is_response`` function, which
	681	has been deprecated.
e39ddf	682
JG	683	Bug Fixes
	684	---------
	685
0fd8ea	686	- URL pattern markers used in URL dispatch are permitted to specify a custom
CM	687	regex. For example, the pattern ``/{foo:\d+}`` means to match ``/12345``
	688	(foo==12345 in the match dictionary) but not ``/abc``. However, custom
0a0edf	689	regexes in a pattern marker which used squiggly brackets did not work. For
CM	690	example, ``/{foo:\d{4}}`` would fail to match ``/1234`` and
	691	``/{foo:\d{1,2}}`` would fail to match ``/1`` or ``/11``. One level of
	692	inner squiggly brackets is now recognized so that the prior two patterns
	693	given as examples now work. See also
	694	https://github.com/Pylons/pyramid/issues/#issue/123.
	695
	696	- Don't send port numbers along with domain information in cookies set by
115c71	697	AuthTktCookieHelper (see https://github.com/Pylons/pyramid/issues/131).
CM	698
	699	- ``pyramid.url.route_path`` (and the shortcut
	700	``pyramid.request.Request.route_url`` method) now include the WSGI
b596e1	701	SCRIPT_NAME at the front of the path if it is not empty (see
CM	702	https://github.com/Pylons/pyramid/issues/135).
	703
	704	- ``pyramid.testing.DummyRequest`` now has a ``script_name`` attribute (the
0b2629	705	empty string).
CM	706
	707	- Don't quote ``:@&+$,`` symbols in ``*elements`` passed to
	708	``pyramid.url.route_url`` or ``pyramid.url.resource_url`` (see
	709	https://github.com/Pylons/pyramid/issues#issue/141).
	710
	711	- Include SCRIPT_NAME in redirects issued by
	712	``pyramid.view.append_slash_notfound_view`` (see
	713	https://github.com/Pylons/pyramid/issues#issue/149).
	714
	715	- Static views registered with ``config.add_static_view`` which also included
	716	a ``permission`` keyword argument would not work as expected, because
	717	``add_static_view`` also registered a route factory internally. Because a
	718	route factory was registered internally, the context checked by the Pyramid
8af47b	719	permission machinery never had an ACL. ``add_static_view`` no longer
CM	720	registers a route with a factory, so the default root factory will be used.
	721
	722	- ``config.add_static_view`` now passes extra keyword arguments it receives
	723	to ``config.add_route`` (calling add_static_view is mostly logically
	724	equivalent to adding a view of the type ``pyramid.static.static_view``
	725	hooked up to a route with a subpath). This makes it possible to pass e.g.,
29a850	726	``factory=`` to ``add_static_view`` to protect a particular static view
CM	727	with a custom ACL.
	728
	729	- ``testing.DummyRequest`` used the wrong registry (the global registry) as
	730	``self.registry`` if a dummy request was created before ``testing.setUp``
	731	was executed (``testing.setUp`` pushes a local registry onto the
	732	threadlocal stack). Fixed by implementing ``registry`` as a property for
	733	DummyRequest instead of eagerly assigning an attribute.
	734	See also https://github.com/Pylons/pyramid/issues/165
	735
ba0a5f	736	- When visiting a URL that represented a static view which resolved to a
CM	737	subdirectory, the ``index.html`` of that subdirectory would not be served
	738	properly. Instead, a redirect to ``/subdir`` would be issued. This has
	739	been fixed, and now visiting a subdirectory that contains an ``index.html``
	740	within a static view returns the index.html properly. See also
	741	https://github.com/Pylons/pyramid/issues/67.
	742
4d9260	743	- Redirects issued by a static view did not take into account any existing
CM	744	``SCRIPT_NAME`` (such as one set by a url mapping composite). Now they do.
	745
	746	- The ``pyramid.wsgi.wsgiapp2`` decorator did not take into account the
	747	``SCRIPT_NAME`` in the origin request.
	748
	749	- The ``pyramid.wsgi.wsgiapp2`` decorator effectively only worked when it
	750	decorated a view found via traversal; it ignored the ``PATH_INFO`` that was
	751	part of a url-dispatch-matched view.
	752
	753	Deprecations
	754	------------
	755
	756	- Deprecated all assignments to ``request.response_*`` attributes (for
	757	example ``request.response_content_type = 'foo'`` is now deprecated).
ed7ffe	758	Assignments and mutations of assignable request attributes that were
CM	759	considered by the framework for response influence are now deprecated:
	760	``response_content_type``, ``response_headerlist``, ``response_status``,
	761	``response_charset``, and ``response_cache_for``. Instead of assigning
	762	these to the request object for later detection by the rendering machinery,
	763	users should use the appropriate API of the Response object created by
	764	accessing ``request.response`` (e.g. code which does
	765	``request.response_content_type = 'abc'`` should be changed to
	766	``request.response.content_type = 'abc'``).
	767
	768	- Passing view-related parameters to
	769	``pyramid.config.Configurator.add_route`` is now deprecated. Previously, a
	770	view was permitted to be connected to a route using a set of ``view*``
	771	parameters passed to the ``add_route`` method of the Configurator. This
	772	was a shorthand which replaced the need to perform a subsequent call to
	773	``add_view``. For example, it was valid (and often recommended) to do::
	774
	775	config.add_route('home', '/', view='mypackage.views.myview',
	776	view_renderer='some/renderer.pt')
	777
bf8c8f	778	Passing ``view*`` arguments to ``add_route`` is now deprecated in favor of
CM	779	connecting a view to a predefined route via ``Configurator.add_view`` using
	780	the route's ``route_name`` parameter. As a result, the above example
ed7ffe	781	should now be spelled::
CM	782
f426e5	783	config.add_route('home', '/')
CM	784	config.add_view('mypackage.views.myview', route_name='home')
	785	renderer='some/renderer.pt')
	786
	787	This deprecation was done to reduce confusion observed in IRC, as well as
	788	to (eventually) reduce documentation burden (see also
	789	https://github.com/Pylons/pyramid/issues/164). A deprecation warning is
	790	now issued when any view-related parameter is passed to
	791	``Configurator.add_route``.
	792
	793	- Passing an ``environ`` dictionary to the ``__call__`` method of a
	794	"traverser" (e.g. an object that implements
	795	``pyramid.interfaces.ITraverser`` such as an instance of
	796	``pyramid.traversal.ResourceTreeTraverser``) as its ``request`` argument
	797	now causes a deprecation warning to be emitted. Consumer code should pass a
	798	``request`` object instead. The fact that passing an environ dict is
	799	permitted has been documentation-deprecated since ``repoze.bfg`` 1.1, and
	800	this capability will be removed entirely in a future version.
	801
	802	- The following (undocumented, dictionary-like) methods of the
4d9260	803	``pyramid.request.Request`` object have been deprecated: ``__contains__``,
CM	804	``__delitem__``, ``__getitem__``, ``__iter__``, ``__setitem__``, ``get``,
	805	``has_key``, ``items``, ``iteritems``, ``itervalues``, ``keys``, ``pop``,
	806	``popitem``, ``setdefault``, ``update``, and ``values``. Usage of any of
	807	these methods will cause a deprecation warning to be emitted. These
	808	methods were added for internal compatibility in ``repoze.bfg`` 1.1 (code
	809	that currently expects a request object expected an environ object in BFG
	810	1.0 and before). In a future version, these methods will be removed
	811	entirely.
	812
920990	813	- Deprecated ``pyramid.view.is_response`` function in favor of (newly-added)
CM	814	``pyramid.request.Request.is_response`` method. Determining if an object
	815	is truly a valid response object now requires access to the registry, which
	816	is only easily available as a request attribute. The
	817	``pyramid.view.is_response`` function will still work until it is removed,
	818	but now may return an incorrect answer under some (very uncommon)
	819	circumstances.
	820
4d9260	821	Behavior Changes
CM	822	----------------
	823
18b25a	824	- The default Mako renderer is now configured to escape all HTML in
MM	825	expression tags. This is intended to help prevent XSS attacks caused by
	826	rendering unsanitized input from users. To revert this behavior in user's
	827	templates, they need to filter the expression through the 'n' filter.
	828	For example, ${ myhtml \| n }.
	829	See https://github.com/Pylons/pyramid/issues/193.
	830
99edc5	831	- A custom request factory is now required to return a request object that
4d9260	832	has a ``response`` attribute (or "reified"/lazy property) if they the
CM	833	request is meant to be used in a view that uses a renderer. This
	834	``response`` attribute should be an instance of the class
	835	``pyramid.response.Response``.
	836
	837	- The JSON and string renderer factories now assign to
	838	``request.response.content_type`` rather than
bf7544	839	``request.response_content_type``.
CM	840
	841	- Each built-in renderer factory now determines whether it should change the
	842	content type of the response by comparing the response's content type
	843	against the response's default content type; if the content type is the
	844	default content type (usually ``text/html``), the renderer changes the
	845	content type (to ``application/json`` or ``text/plain`` for JSON and string
	846	renderers respectively).
4d9260	847
ba0a5f	848	- The ``pyramid.wsgi.wsgiapp2`` now uses a slightly different method of
CM	849	figuring out how to "fix" ``SCRIPT_NAME`` and ``PATH_INFO`` for the
	850	downstream application. As a result, those values may differ slightly from
	851	the perspective of the downstream application (for example, ``SCRIPT_NAME``
	852	will now never possess a trailing slash).
	853
bca03f	854	- Previously, ``pyramid.request.Request`` inherited from
CM	855	``webob.request.Request`` and implemented ``__getattr__``, ``__setattr__``
	856	and ``__delattr__`` itself in order to overidde "adhoc attr" WebOb behavior
	857	where attributes of the request are stored in the environ. Now,
	858	``pyramid.request.Request`` object inherits from (the more recent)
	859	``webob.request.BaseRequest`` instead of ``webob.request.Request``, which
	860	provides the same behavior. ``pyramid.request.Request`` no longer
	861	implements its own ``__getattr__``, ``__setattr__`` or ``__delattr__`` as a
	862	result.
	863
966b5c	864	- ``pyramid.response.Response`` is now a subclass of
99edc5	865	``webob.response.Response`` (in order to directly implement the
CM	866	``pyramid.interfaces.IResponse`` interface).
	867
53d11e	868	- The "exception response" objects importable from ``pyramid.httpexceptions``
CM	869	(e.g. ``HTTPNotFound``) are no longer just import aliases for classes that
	870	actually live in ``webob.exc``. Instead, we've defined our own exception
	871	classes within the module that mirror and emulate the ``webob.exc``
1e5e31	872	exception response objects almost entirely. See the "Design Defense" doc
CM	873	section named "Pyramid Uses its Own HTTP Exception Classes" for more
	874	information.
53d11e	875
d868ff	876	Backwards Incompatibilities
CM	877	---------------------------
99edc5	878
5484e3	879	- Pyramid no longer supports Python 2.4. Python 2.5 or better is required to
CM	880	run Pyramid 1.1+.
	881
99edc5	882	- The Pyramid router now, by default, expects response objects returned from
d868ff	883	view callables to implement the ``pyramid.interfaces.IResponse`` interface.
CM	884	Unlike the Pyramid 1.0 version of this interface, objects which implement
	885	IResponse now must define a ``__call__`` method that accepts ``environ``
	886	and ``start_response``, and which returns an ``app_iter`` iterable, among
	887	other things. Previously, it was possible to return any object which had
	888	the three WebOb ``app_iter``, ``headerlist``, and ``status`` attributes as
	889	a response, so this is a backwards incompatibility. It is possible to get
	890	backwards compatibility back by registering an adapter to IResponse from
	891	the type of object you're now returning from view callables. See the
	892	section in the Hooks chapter of the documentation entitled "Changing How
	893	Pyramid Treats View Responses".
	894
	895	- The ``pyramid.interfaces.IResponse`` interface is now much more extensive.
	896	Previously it defined only ``app_iter``, ``status`` and ``headerlist``; now
	897	it is basically intended to directly mirror the ``webob.Response`` API,
	898	which has many methods and attributes.
966b5c	899
d0a5f0	900	- The ``pyramid.httpexceptions`` classes named ``HTTPFound``,
CM	901	``HTTPMultipleChoices``, ``HTTPMovedPermanently``, ``HTTPSeeOther``,
	902	``HTTPUseProxy``, and ``HTTPTemporaryRedirect`` now accept ``location`` as
	903	their first positional argument rather than ``detail``. This means that
	904	you can do, e.g. ``return pyramid.httpexceptions.HTTPFound('http://foo')``
	905	rather than ``return
	906	pyramid.httpexceptions.HTTPFound(location='http//foo')`` (the latter will
	907	of course continue to work).
	908
0f7831	909	Dependencies
CM	910	------------
	911
dad904	912	- Pyramid now depends on WebOb >= 1.0.2 as tests depend on the bugfix in that
CM	913	release: "Fix handling of WSGI environs with missing ``SCRIPT_NAME``".
0f7831	914	(Note that in reality, everyone should probably be using 1.0.4 or better
CM	915	though, as WebOb 1.0.2 and 1.0.3 were effectively brownbag releases.)
	916