RedHatTraining/pyramid.git

first cut at indicating that only some predicates are negatable

Chris McDonough

2013-07-31 5fc0d36724a6197c8c0106e846d8e78e1219b1fe

commit \| author \| age
0d96b7	1	Next Release
2d9314	2	============
MM	3
	4	Features
	5	--------
	6
32333e	7	- Add the ability to invert the result of any view, route, or subscriber
CM	8	predicate using the ``not_`` class. For example::
	9
	10	from pyramid.config import not_
	11
	12	@view_config(route_name='myroute', request_method=not_('POST'))
	13	def myview(request): ...
	14
	15	The above example will ensure that the view is called if the request method
	16	is not POST (at least if no other view is more specific).
	17
	18	The :class:`pyramid.config.not_` class can be used against any value that is
	19	a predicate value passed in any of these contexts:
	20
	21	- ``pyramid.config.Configurator.add_view``
	22
	23	- ``pyramid.config.Configurator.add_route``
	24
	25	- ``pyramid.config.Configurator.add_subscriber``
	26
	27	- ``pyramid.view.view_config``
	28
	29	- ``pyramid.events.subscriber``
	30
a17863	31	- ``scripts/prequest.py``: add support for submitting ``PUT`` and ``PATCH``
CM	32	requests. See https://github.com/Pylons/pyramid/pull/1033. add support for
0d96b7	33	submitting ``OPTIONS`` and ``PROPFIND`` requests, and allow users to specify
a17863	34	basic authentication credentials in the request via a ``--login`` argument to
CM	35	the script. See https://github.com/Pylons/pyramid/pull/1039.
f0f92b	36
2d9314	37	- ``ACLAuthorizationPolicy`` supports ``__acl__`` as a callable. This
MM	38	removes the ambiguity between the potential ``AttributeError`` that would
	39	be raised on the ``context`` when the property was not defined and the
	40	``AttributeError`` that could be raised from any user-defined code within
	41	a dynamic property. It is recommended to define a dynamic ACL as a callable
	42	to avoid this ambiguity. See https://github.com/Pylons/pyramid/issues/735.
	43
ff41f8	44	- Allow a protocol-relative URL (e.g. ``//example.com/images``) to be passed to
WS	45	``pyramid.config.Configurator.add_static_view``. This allows
	46	externally-hosted static URLs to be generated based on the current protocol.
	47
188aa7	48	- The ``AuthTktAuthenticationPolicy`` has a new ``parent_domain`` option to
WA	49	set the authentication cookie as a wildcard cookie on the parent domain. This
	50	is useful if you have multiple sites sharing the same domain.
	51
23a7c6	52	- The ``AuthTktAuthenticationPolicy`` now supports IPv6 addresses when using
MM	53	the ``include_ip=True`` option. This is possibly incompatible with
	54	alternative ``auth_tkt`` implementations, as the specification does not
	55	define how to properly handle IPv6. See
	56	https://github.com/Pylons/pyramid/issues/831.
	57
38844f	58	- Make it possible to use variable arguments via
MM	59	``pyramid.paster.get_appsettings``. This also allowed the generated
	60	``initialize_db`` script from the ``alchemy`` scaffold to grow support
	61	for options in the form ``a=1 b=2`` so you can fill in
	62	values in a parameterized ``.ini`` file, e.g.
	63	``initialize_myapp_db etc/development.ini a=1 b=2``.
	64	See https://github.com/Pylons/pyramid/pull/911
	65
fab845	66	- The ``request.session.check_csrf_token()`` method and the ``check_csrf`` view
CM	67	predicate now take into account the value of the HTTP header named
	68	``X-CSRF-Token`` (as well as the ``csrf_token`` form parameter, which they
	69	always did). The header is tried when the form parameter does not exist.
	70
b6a4d4	71	- View lookup will now search for valid views based on the inheritance
MM	72	hierarchy of the context. It tries to find views based on the most
	73	specific context first, and upon predicate failure, will move up the
	74	inheritance chain to test views found by the super-type of the context.
	75	In the past, only the most specific type containing views would be checked
	76	and if no matching view could be found then a PredicateMismatch would be
	77	raised. Now predicate mismatches don't hide valid views registered on
0d96b7	78	super-types. Here's an example that now works:
9e1e6d	79
b6a4d4	80	.. code-block:: python
9e1e6d	81
b6a4d4	82	class IResource(Interface):
07c189	83
b6a4d4	84	...
9e1e6d	85
b6a4d4	86	@view_config(context=IResource)
MM	87	def get(context, request):
07c189	88
b6a4d4	89	...
9e1e6d	90
b6a4d4	91	@view_config(context=IResource, request_method='POST')
MM	92	def post(context, request):
07c189	93
b6a4d4	94	...
9e1e6d	95
b6a4d4	96	@view_config(context=IResource, request_method='DELETE')
MM	97	def delete(context, request):
07c189	98
b6a4d4	99	...
9e1e6d	100
b6a4d4	101	@implementor(IResource)
MM	102	class MyResource:
07c189	103
b6a4d4	104	...
MM	105
	106	@view_config(context=MyResource, request_method='POST')
	107	def override_post(context, request):
07c189	108
b6a4d4	109	...
9e1e6d	110
AL	111	Previously the override_post view registration would hide the get
	112	and delete views in the context of MyResource -- leading to a
	113	predicate mismatch error when trying to use GET or DELETE
	114	methods. Now the views are found and no predicate mismatch is
	115	raised.
6b9700	116	See https://github.com/Pylons/pyramid/pull/786 and
75fc4a	117	https://github.com/Pylons/pyramid/pull/1004 and
MM	118	https://github.com/Pylons/pyramid/pull/1046
9e1e6d	119
0d96b7	120	Bug Fixes
CM	121	---------
	122
	123	- Make the ``pyramid.config.assets.PackageOverrides`` object implement the API
	124	for ``__loader__`` objects specified in PEP 302. Proxies to the
	125	``__loader__`` set by the importer, if present; otherwise, raises
	126	``NotImplementedError``. This makes Pyramid static view overrides work
	127	properly under Python 3.3 (previously they would not). See
	128	https://github.com/Pylons/pyramid/pull/1015 for more information.
	129
	130	- ``mako_templating``: added defensive workaround for non-importability of
	131	``mako`` due to upstream ``markupsafe`` dropping Python 3.2 support. Mako
	132	templating will no longer work under the combination of MarkupSafe 0.17 and
	133	Python 3.2 (although the combination of MarkupSafe 0.17 and Python 3.3 or any
	134	supported Python 2 version will work OK).
	135
ea278e	136	- Spaces and dots may now be in mako renderer template paths. This was
MM	137	broken when support for the new makodef syntax was added in 1.4a1.
	138	See https://github.com/Pylons/pyramid/issues/950
	139
20c57e	140	- ``pyramid.debug_authorization=true`` will now correctly print out
MM	141	``Allowed`` for views registered with ``NO_PERMISSION_REQUIRED`` instead
	142	of invoking the ``permits`` method of the authorization policy.
	143	See https://github.com/Pylons/pyramid/issues/954
	144
c35b29	145	- Pyramid failed to install on some systems due to being packaged with
MM	146	some test files containing higher order characters in their names. These
	147	files have now been removed. See
	148	https://github.com/Pylons/pyramid/issues/981
	149
050b71	150	- ``pyramid.testing.DummyResource`` didn't define ``__bool__``, so code under
0d96b7	151	Python 3 would use ``__len__`` to find truthiness; this usually caused an
CM	152	instance of DummyResource to be "falsy" instead of "truthy". See
	153	https://github.com/Pylons/pyramid/pull/1032
050b71	154
96ab9f	155	1.4 (2012-12-18)
CM	156	================
758fa2	157
CM	158	Docs
	159	----
	160
	161	- Fix functional tests in the ZODB tutorial
	162
e609e1	163	1.4b3 (2012-12-10)
CM	164	==================
	165
	166	- Packaging release only, no code changes. 1.4b2 was a brownbag release due to
	167	missing directories in the tarball.
	168
a7e0e6	169	1.4b2 (2012-12-10)
CM	170	==================
	171
	172	Docs
	173	----
	174
	175	- Scaffolding is now PEP-8 compliant (at least for a brief shining moment).
	176
	177	- Tutorial improvements.
ed1419	178
MM	179	Backwards Incompatibilities
	180	---------------------------
	181
	182	- Modified the ``_depth`` argument to ``pyramid.view.view_config`` to accept
	183	a value relative to the invocation of ``view_config`` itself. Thus, when it
	184	was previously expecting a value of ``1`` or greater, to reflect that
	185	the caller of ``view_config`` is 1 stack frame away from ``venusian.attach``,
	186	this implementation detail is now hidden.
	187
a078e1	188	- Modified the ``_backframes`` argument to ``pyramid.util.action_method`` in a
CM	189	similar way to the changes described to ``_depth`` above. This argument
	190	remains undocumented, but might be used in the wild by some insane person.
	191
1608b2	192	1.4b1 (2012-11-21)
CM	193	==================
0ccdc2	194
71cd93	195	Features
CM	196	--------
	197
	198	- Small microspeed enhancement which anticipates that a
	199	``pyramid.response.Response`` object is likely to be returned from a view.
	200	Some code is shortcut if the class of the object returned by a view is this
	201	class. A similar microoptimization was done to
	202	``pyramid.request.Request.is_response``.
	203
9132f6	204	- Make it possible to use variable arguments on ``p*`` commands (``pserve``,
CM	205	``pshell``, ``pviews``, etc) in the form ``a=1 b=2`` so you can fill in
	206	values in parameterized ``.ini`` file, e.g. ``pshell etc/development.ini
6ba0fc	207	http_port=8080``. See https://github.com/Pylons/pyramid/pull/714
9132f6	208
f700d3	209	- A somewhat advanced and obscure feature of Pyramid event handlers is their
CM	210	ability to handle "multi-interface" notifications. These notifications have
	211	traditionally presented multiple objects to the subscriber callable. For
	212	instance, if an event was sent by code like this::
28fc3d	213
CM	214	registry.notify(event, context)
	215
	216	In the past, in order to catch such an event, you were obligated to write and
	217	register an event subscriber that mentioned both the event and the context in
	218	its argument list::
	219
	220	@subscriber([SomeEvent, SomeContextType])
f700d3	221	def asubscriber(event, context):
28fc3d	222	pass
CM	223
f700d3	224	In many subscriber callables registered this way, it was common for the logic
CM	225	in the subscriber callable to completely ignore the second and following
	226	arguments (e.g. ``context`` in the above example might be ignored), because
	227	they usually existed as attributes of the event anyway. You could usually
a3810e	228	get the same value by doing ``event.context`` or similar.
f700d3	229
CM	230	The fact that you needed to put an extra argument which you usually ignored
	231	in the subscriber callable body was only a minor annoyance until we added
a3810e	232	"subscriber predicates", used to narrow the set of circumstances under which
CM	233	a subscriber will be executed, in a prior 1.4 alpha release. Once those were
	234	added, the annoyance was escalated, because subscriber predicates needed to
	235	accept the same argument list and arity as the subscriber callables that they
	236	were configured against. So, for example, if you had these two subscriber
	237	registrations in your code::
28fc3d	238
CM	239	@subscriber([SomeEvent, SomeContextType])
f700d3	240	def asubscriber(event, context):
CM	241	pass
	242
	243	@subscriber(SomeOtherEvent)
	244	def asubscriber(event):
	245	pass
	246
	247	And you wanted to use a subscriber predicate::
	248
	249	@subscriber([SomeEvent, SomeContextType], mypredicate=True)
a3810e	250	def asubscriber1(event, context):
f700d3	251	pass
CM	252
	253	@subscriber(SomeOtherEvent, mypredicate=True)
a3810e	254	def asubscriber2(event):
f700d3	255	pass
CM	256
a3810e	257	If an existing ``mypredicate`` subscriber predicate had been written in such
CM	258	a way that it accepted only one argument in its ``__call__``, you could not
	259	use it against a subscription which named more than one interface in its
	260	subscriber interface list. Similarly, if you had written a subscriber
	261	predicate that accepted two arguments, you couldn't use it against a
	262	registration that named only a single interface type.
	263
	264	For example, if you created this predicate::
f700d3	265
CM	266	class MyPredicate(object):
	267	# portions elided...
	268	def __call__(self, event):
	269	return self.val == event.context.foo
	270
a3810e	271	It would not work against a multi-interface-registered subscription, so in
CM	272	the above example, when you attempted to use it against ``asubscriber1``, it
	273	would fail at runtime with a TypeError, claiming something was attempting to
	274	call it with too many arguments.
f700d3	275
a3810e	276	To hack around this limitation, you were obligated to design the
CM	277	``mypredicate`` predicate to expect to receive in its ``__call__`` either a
	278	single ``event`` argument (a SomeOtherEvent object) or a pair of arguments
	279	(a SomeEvent object and a SomeContextType object), presumably by doing
	280	something like this::
f700d3	281
CM	282	class MyPredicate(object):
	283	# portions elided...
	284	def __call__(self, event, context=None):
	285	return self.val == event.context.foo
	286
	287	This was confusing and bad.
	288
	289	In order to allow people to ignore unused arguments to subscriber callables
	290	and to normalize the relationship between event subscribers and subscriber
	291	predicates, we now allow both subscribers and subscriber predicates to accept
	292	only a single ``event`` argument even if they've been subscribed for
	293	notifications that involve multiple interfaces. Subscribers and subscriber
	294	predicates that accept only one argument will receive the first object passed
	295	to ``notify``; this is typically (but not always) the event object. The
	296	other objects involved in the subscription lookup will be discarded. You can
	297	now write an event subscriber that accepts only ``event`` even if it
	298	subscribes to multiple interfaces::
	299
	300	@subscriber([SomeEvent, SomeContextType])
	301	def asubscriber(event):
28fc3d	302	# this will work!
CM	303
f700d3	304	This prevents you from needing to match the subscriber callable parameters to
CM	305	the subscription type unnecessarily, especially when you don't make use of
	306	any argument in your subscribers except for the event object itself.
	307
	308	Note, however, that if the event object is not the first
	309	object in the call to ``notify``, you'll run into trouble. For example, if
	310	notify is called with the context argument first::
28fc3d	311
CM	312	registry.notify(context, event)
	313
f700d3	314	You won't be able to take advantage of the event-only feature. It will
CM	315	"work", but the object received by your event handler won't be the event
	316	object, it will be the context object, which won't be very useful::
28fc3d	317
CM	318	@subscriber([SomeContextType, SomeEvent])
f700d3	319	def asubscriber(event):
28fc3d	320	# bzzt! you'll be getting the context here as ``event``, and it'll
CM	321	# be useless
	322
	323	Existing multiple-argument subscribers continue to work without issue, so you
	324	should continue use those if your system notifies using multiple interfaces
	325	and the first interface is not the event interface. For example::
	326
	327	@subscriber([SomeContextType, SomeEvent])
f700d3	328	def asubscriber(context, event):
28fc3d	329	# this will still work!
CM	330
	331	The event-only feature makes it possible to use a subscriber predicate that
	332	accepts only a request argument within both multiple-interface subscriber
f700d3	333	registrations and single-interface subscriber registrations. You needn't
CM	334	make slightly different variations of predicates depending on the
	335	subscription type arguments. Instead, just write all your subscriber
	336	predicates so they only accept ``event`` in their ``__call__`` and they'll be
	337	useful across all registrations for subscriptions that use an event as their
	338	first argument, even ones which accept more than just ``event``.
28fc3d	339
f700d3	340	However, the same caveat applies to predicates as to subscriber callables: if
CM	341	you're subscribing to a multi-interface event, and the first interface is not
	342	the event interface, the predicate won't work properly. In such a case,
	343	you'll need to match the predicate ``__call__`` argument ordering and
	344	composition to the ordering of the interfaces. For example, if the
	345	registration for the subscription uses ``[SomeContext, SomeEvent]``, you'll
	346	need to reflect that in the ordering of the parameters of the predicate's
	347	``__call__`` method::
28fc3d	348
CM	349	def __call__(self, context, event):
	350	return event.request.path.startswith(self.val)
	351
f700d3	352	tl;dr: 1) When using multi-interface subscriptions, always use the event type
CM	353	as the first subscription registration argument and 2) When 1 is true, use
	354	only ``event`` in your subscriber and subscriber predicate parameter lists,
	355	no matter how many interfaces the subscriber is notified with. This
	356	combination will result in the maximum amount of reusability of subscriber
	357	predicates and the least amount of thought on your part. Drink responsibly.
28fc3d	358
0ccdc2	359	Bug Fixes
CM	360	---------
	361
	362	- A failure when trying to locate the attribute ``__text__`` on route and view
	363	predicates existed when the ``debug_routematch`` setting was true or when the
	364	``pviews`` command was used. See https://github.com/Pylons/pyramid/pull/727
	365
b5e444	366	Documentation
CM	367	-------------
	368
	369	- Sync up tutorial source files with the files that are rendered by the
	370	scaffold that each uses.
	371
948068	372	1.4a4 (2012-11-14)
CM	373	==================
c7337b	374
CM	375	Features
	376	--------
	377
19b820	378	- ``pyramid.authentication.AuthTktAuthenticationPolicy`` has been updated to
MM	379	support newer hashing algorithms such as ``sha512``. Existing applications
39ef68	380	should consider updating if possible for improved security over the default
CM	381	md5 hashing.
19b820	382
c7337b	383	- Added an ``effective_principals`` route and view predicate.
CM	384
07c9ee	385	- Do not allow the userid returned from the ``authenticated_userid`` or the
CM	386	userid that is one of the list of principals returned by
	387	``effective_principals`` to be either of the strings ``system.Everyone`` or
	388	``system.Authenticated`` when any of the built-in authorization policies that
	389	live in ``pyramid.authentication`` are in use. These two strings are
	390	reserved for internal usage by Pyramid and they will not be accepted as valid
	391	userids.
	392
ca4656	393	- Slightly better debug logging from
MM	394	``pyramid.authentication.RepozeWho1AuthenticationPolicy``.
47146e	395
39ef68	396	- ``pyramid.security.view_execution_permitted`` used to return ``True`` if no
926fb6	397	view could be found. It now raises a ``TypeError`` exception in that case, as
CM	398	it doesn't make sense to assert that a nonexistent view is
	399	execution-permitted. See https://github.com/Pylons/pyramid/issues/299.
cb745b	400
a8d71c	401	- Allow a ``_depth`` argument to ``pyramid.view.view_config``, which will
CM	402	permit limited composition reuse of the decorator by other software that
	403	wants to provide custom decorators that are much like view_config.
	404
170124	405	- Allow an iterable of decorators to be passed to
MM	406	``pyramid.config.Configurator.add_view``. This allows views to be wrapped
	407	by more than one decorator without requiring combining the decorators
	408	yourself.
	409
a007a4	410	Bug Fixes
CM	411	---------
	412
	413	- In the past if a renderer returned ``None``, the body of the resulting
	414	response would be set explicitly to the empty string. Instead, now, the body
	415	is left unchanged, which allows the renderer to set a body itself by using
	416	e.g. ``request.response.body = b'foo'``. The body set by the renderer will
	417	be unmolested on the way out. See
	418	https://github.com/Pylons/pyramid/issues/709
	419
34d4cd	420	- In uncommon cases, the ``pyramid_excview_tween_factory`` might have
CM	421	inadvertently raised a ``KeyError`` looking for ``request_iface`` as an
	422	attribute of the request. It no longer fails in this case. See
	423	https://github.com/Pylons/pyramid/issues/700
048754	424
267dbd	425	- Be more tolerant of potential error conditions in ``match_param`` and
CM	426	``physical_path`` predicate implementations; instead of raising an exception,
	427	return False.
	428
39ef68	429	- ``pyramid.view.render_view`` was not functioning properly under Python 3.x
CM	430	due to a byte/unicode discrepancy. See
cd8ac8	431	https://github.com/Pylons/pyramid/issues/721
f89cfc	432
ca3df8	433	Deprecations
MM	434	------------
	435
39ef68	436	- ``pyramid.authentication.AuthTktAuthenticationPolicy`` will emit a warning if
CM	437	an application is using the policy without explicitly passing a ``hashalg``
	438	argument. This is because the default is "md5" which is considered
	439	theoretically subject to collision attacks. If you really want "md5" then you
	440	must specify it explicitly to get rid of the warning.
	441
	442	Documentation
	443	-------------
	444
	445	- All of the tutorials that use
	446	``pyramid.authentication.AuthTktAuthenticationPolicy`` now explicitly pass
	447	``sha512`` as a ``hashalg`` argument.
	448
ca3df8	449
66fe1d	450	Internals
CM	451	---------
	452
	453	- Move ``TopologicalSorter`` from ``pyramid.config.util`` to ``pyramid.util``,
	454	move ``CyclicDependencyError`` from ``pyramid.config.util`` to
	455	``pyramid.exceptions``, rename ``Singleton`` to ``Sentinel`` and move from
ca4656	456	``pyramid.config.util`` to ``pyramid.util``; this is in an effort to
048754	457	move that stuff that may be an API one day out of ``pyramid.config.util``,
66fe1d	458	because that package should never be imported from non-Pyramid code.
CM	459	TopologicalSorter is still not an API, but may become one.
	460
39ef68	461	- Get rid of shady monkeypatching of ``pyramid.request.Request`` and
CM	462	``pyramid.response.Response`` done within the ``__init__.py`` of Pyramid.
	463	Webob no longer relies on this being done. Instead, the ResponseClass
	464	attribute of the Pyramid Request class is assigned to the Pyramid response
	465	class; that's enough to satisfy WebOb and behave as it did before with the
	466	monkeypatching.
	467
4a6cca	468	1.4a3 (2012-10-26)
CM	469	==================
d6fb00	470
CM	471	Bug Fixes
	472	---------
	473
06a904	474	- The match_param predicate's text method was fixed to sort its values.
CM	475	Part of https://github.com/Pylons/pyramid/pull/705
	476
d6fb00	477	- 1.4a ``pyramid.scripting.prepare`` behaved differently than 1.3 series
CM	478	function of same name. In particular, if passed a request, it would not
	479	set the ``registry`` attribute of the request like 1.3 did. A symptom
	480	would be that passing a request to ``pyramid.paster.bootstrap`` (which uses
	481	the function) that did not have a ``registry`` attribute could assume that
	482	the registry would be attached to the request by Pyramid. This assumption
	483	could be made in 1.3, but not in 1.4. The assumption can now be made in
	484	1.4 too (a registry is attached to a request passed to bootstrap or
	485	prepare).
	486
66d277	487	- When registering a view configuration that named a Chameleon ZPT renderer
CM	488	with a macro name in it (e.g. ``renderer='some/template#somemacro.pt``) as
043ccd	489	well as a view configuration without a macro name in it that pointed to the
9937a4	490	same template (e.g. ``renderer='some/template.pt'``), internal caching could
66d277	491	confuse the two, and your code might have rendered one instead of the
CM	492	other.
	493
1273d5	494	Features
CM	495	--------
	496
c25a8f	497	- Allow multiple values to be specified to the ``request_param`` view/route
CM	498	predicate as a sequence. Previously only a single string value was allowed.
	499	See https://github.com/Pylons/pyramid/pull/705
	500
	501	- Comments with references to documentation sections placed in scaffold
	502	``.ini`` files.
	503
	504	- Added an HTTP Basic authentication policy
	505	at ``pyramid.authentication.BasicAuthAuthenticationPolicy``.
	506
1273d5	507	- The Configurator ``testing_securitypolicy`` method now returns the policy
CM	508	object it creates.
	509
	510	- The Configurator ``testing_securitypolicy`` method accepts two new
	511	arguments: ``remember_result`` and ``forget_result``. If supplied, these
	512	values influence the result of the policy's ``remember`` and ``forget``
	513	methods, respectively.
	514
	515	- The DummySecurityPolicy created by ``testing_securitypolicy`` now sets a
	516	``forgotten`` value on the policy (the value ``True``) when its ``forget``
	517	method is called.
	518
	519	- The DummySecurityPolicy created by ``testing_securitypolicy`` now sets a
	520	``remembered`` value on the policy, which is the value of the ``principal``
	521	argument it's called with when its ``remember`` method is called.
	522
c25a8f	523	- New ``physical_path`` view predicate. If specified, this value should be a
CM	524	string or a tuple representing the physical traversal path of the context
	525	found via traversal for this predicate to match as true. For example:
	526	``physical_path='/'`` or ``physical_path='/a/b/c'`` or ``physical_path=('',
	527	'a', 'b', 'c')``. This is not a path prefix match or a regex, it's a
	528	whole-path match. It's useful when you want to always potentially show a
	529	view when some object is traversed to, but you can't be sure about what kind
	530	of object it will be, so you can't use the ``context`` predicate. The
	531	individual path elements inbetween slash characters or in tuple elements
	532	should be the Unicode representation of the name of the resource and should
	533	not be encoded in any way.
	534
072cbf	535	1.4a2 (2012-09-27)
CM	536	==================
68c25d	537
d27bc7	538	Bug Fixes
CM	539	---------
	540
4388d3	541	- When trying to determine Mako defnames and Chameleon macro names in asset
CM	542	specifications, take into account that the filename may have a hyphen in
	543	it. See https://github.com/Pylons/pyramid/pull/692
d27bc7	544
68c25d	545	Features
CM	546	--------
	547
	548	- A new ``pyramid.session.check_csrf_token`` convenience function was added.
	549
80cd0b	550	- A ``check_csrf`` view predicate was added. For example, you can now do
CM	551	``config.add_view(someview, check_csrf=True)``. When the predicate is
	552	checked, if the ``csrf_token`` value in ``request.params`` matches the CSRF
	553	token in the request's session, the view will be permitted to execute.
	554	Otherwise, it will not be permitted to execute.
68c25d	555
098599	556	- Add ``Base.metadata.bind = engine`` to alchemy template, so that tables
CM	557	defined imperatively will work.
	558
	559	Documentation
	560	-------------
	561
	562	- update wiki2 SQLA tutorial with the changes required after inserting
	563	``Base.metadata.bind = engine`` into the alchemy scaffold.
	564
ce1e86	565	1.4a1 (2012-09-16)
CM	566	==================
f6bd88	567
a39dd2	568	Bug Fixes
CM	569	---------
	570
1794b4	571	- Forward port from 1.3 branch: When no authentication policy was configured,
CM	572	a call to ``pyramid.security.effective_principals`` would unconditionally
	573	return the empty list. This was incorrect, it should have unconditionally
	574	returned ``[Everyone]``, and now does.
8782de	575
3074e7	576	- Explicit url dispatch regexes can now contain colons.
CM	577	https://github.com/Pylons/pyramid/issues/629
	578
e65251	579	- On at least one 64-bit Ubuntu system under Python 3.2, using the
CM	580	``view_config`` decorator caused a ``RuntimeError: dictionary changed size
	581	during iteration`` exception. It no longer does. See
	582	https://github.com/Pylons/pyramid/issues/635 for more information.
	583
8b2675	584	- In Mako Templates lookup, check if the uri is already adjusted and bring
BL	585	it back to an asset spec. Normally occurs with inherited templates or
	586	included components.
	587	https://github.com/Pylons/pyramid/issues/606
	588	https://github.com/Pylons/pyramid/issues/607
	589
7853bc	590	- In Mako Templates lookup, check for absolute uri (using mako directories)
BL	591	when mixing up inheritance with asset specs.
	592	https://github.com/Pylons/pyramid/issues/662
	593
75a8ff	594	- HTTP Accept headers were not being normalized causing potentially
MM	595	conflicting view registrations to go unnoticed. Two views that only
	596	differ in the case ('text/html' vs. 'text/HTML') will now raise an error.
	597	https://github.com/Pylons/pyramid/pull/620
	598
a9289d	599	- Forward-port from 1.3 branch: when registering multiple views with an
CM	600	``accept`` predicate in a Pyramid application runing under Python 3, you
	601	might have received a ``TypeError: unorderable types: function() <
	602	function()`` exception.
	603
de797c	604	Features
CM	605	--------
a39dd2	606
d24659	607	- Configurator.add_directive now accepts arbitrary callables like partials or
CM	608	objects implementing ``__call__`` which dont have ``__name__`` and
	609	``__doc__`` attributes. See https://github.com/Pylons/pyramid/issues/621
	610	and https://github.com/Pylons/pyramid/pull/647.
	611
95f766	612	- Third-party custom view, route, and subscriber predicates can now be added
CM	613	for use by view authors via
	614	``pyramid.config.Configurator.add_view_predicate``,
	615	``pyramid.config.Configurator.add_route_predicate`` and
	616	``pyramid.config.Configurator.add_subscriber_predicate``. So, for example,
0196b2	617	doing this::
CM	618
	619	config.add_view_predicate('abc', my.package.ABCPredicate)
	620
	621	Might allow a view author to do this in an application that configured that
	622	predicate::
	623
	624	@view_config(abc=1)
	625
95f766	626	Similar features exist for ``add_route``, and ``add_subscriber``. See
CM	627	"Adding A Third Party View, Route, or Subscriber Predicate" in the Hooks
	628	chapter for more information.
0196b2	629
735abf	630	Note that changes made to support the above feature now means that only
CM	631	actions registered using the same "order" can conflict with one another.
	632	It used to be the case that actions registered at different orders could
	633	potentially conflict, but to my knowledge nothing ever depended on this
	634	behavior (it was a bit silly).
	635
de797c	636	- Custom objects can be made easily JSON-serializable in Pyramid by defining
CM	637	a ``__json__`` method on the object's class. This method should return
	638	values natively serializable by ``json.dumps`` (such as ints, lists,
	639	dictionaries, strings, and so forth).
077fa3	640
e012aa	641	- The JSON renderer now allows for the definition of custom type adapters to
CM	642	convert unknown objects to JSON serializations.
	643
360f25	644	- As of this release, the ``request_method`` predicate, when used, will also
CM	645	imply that ``HEAD`` is implied when you use ``GET``. For example, using
	646	``@view_config(request_method='GET')`` is equivalent to using
561a44	647	``@view_config(request_method=('GET', 'HEAD'))``. Using
360f25	648	``@view_config(request_method=('GET', 'POST')`` is equivalent to using
CM	649	``@view_config(request_method=('GET', 'HEAD', 'POST')``. This is because
	650	HEAD is a variant of GET that omits the body, and WebOb has special support
	651	to return an empty body when a HEAD is used.
15c40a	652
023c88	653	- ``config.add_request_method`` has been introduced to support extending
2c2534	654	request objects with arbitrary callables. This method expands on the
MM	655	previous ``config.set_request_property`` by supporting methods as well as
	656	properties. This method now causes less code to be executed at
	657	request construction time than ``config.set_request_property`` in
	658	version 1.3.
fcb209	659
2c2534	660	- Don't add a ``?`` to URLs generated by ``request.resource_url`` if the
fcb209	661	``query`` argument is provided but empty.
CM	662
2c2534	663	- Don't add a ``?`` to URLs generated by ``request.route_url`` if the
fcb209	664	``_query`` argument is provided but empty.
988035	665
CM	666	- The static view machinery now raises (rather than returns) ``HTTPNotFound``
	667	and ``HTTPMovedPermanently`` exceptions, so these can be caught by the
cec2b0	668	Not Found View (and other exception views).
ea009a	669
54d3e3	670	- The Mako renderer now supports a def name in an asset spec. When the def
8b55a6	671	name is present in the asset spec, the system will render the template def
CM	672	within the template and will return the result. An example asset spec is
	673	``package:path/to/template#defname.mako``. This will render the def named
54d3e3	674	``defname`` inside the ``template.mako`` template instead of rendering the
CM	675	entire template. The old way of returning a tuple in the form
	676	``('defname', {})`` from the view is supported for backward compatibility,
8b55a6	677
CM	678	- The Chameleon ZPT renderer now accepts a macro name in an asset spec. When
	679	the macro name is present in the asset spec, the system will render the
	680	macro listed as a ``define-macro`` and return the result instead of
	681	rendering the entire template. An example asset spec:
	682	``package:path/to/template#macroname.pt``. This will render the macro
	683	defined as ``macroname`` within the ``template.pt`` template instead of the
	684	entire templae.
61a57e	685
CM	686	- When there is a predicate mismatch exception (seen when no view matches for
	687	a given request due to predicates not working), the exception now contains
	688	a textual description of the predicate which didn't match.
6b180c	689
CM	690	- An ``add_permission`` directive method was added to the Configurator. This
	691	directive registers a free-standing permission introspectable into the
	692	Pyramid introspection system. Frameworks built atop Pyramid can thus use
08c221	693	the ``permissions`` introspectable category data to build a
6b180c	694	comprehensive list of permissions supported by a running system. Before
CM	695	this method was added, permissions were already registered in this
	696	introspectable category as a side effect of naming them in an ``add_view``
	697	call, this method just makes it possible to arrange for a permission to be
	698	put into the ``permissions`` introspectable category without naming it
	699	along with an associated view. Here's an example of usage of
	700	``add_permission``::
	701
	702	config = Configurator()
	703	config.add_permission('view')
2c2534	704
45b6e1	705	- The ``UnencryptedCookieSessionFactoryConfig`` now accepts
MM	706	``signed_serialize`` and ``signed_deserialize`` hooks which may be used
	707	to influence how the sessions are marshalled (by default this is done
	708	with HMAC+pickle).
	709
28dba0	710	- ``pyramid.testing.DummyRequest`` now supports methods supplied by the
CM	711	``pyramid.util.InstancePropertyMixin`` class such as ``set_property``.
735987	712
CM	713	- Request properties and methods added via ``config.set_request_property`` or
	714	``config.add_request_method`` are now available to tweens.
	715
	716	- Request properties and methods added via ``config.set_request_property`` or
	717	``config.add_request_method`` are now available in the request object
	718	returned from ``pyramid.paster.bootstrap``.
	719
dc8b49	720	- ``request.context`` of environment request during ``bootstrap`` is now the
CM	721	root object if a context isn't already set on a provided request.
	722
07cb8f	723	- The ``pyramid.decorator.reify`` function is now an API, and was added to
CM	724	the API documentation.
	725
97150c	726	- Added the ``pyramid.testing.testConfig`` context manager, which can be used
CM	727	to generate a configurator in a test, e.g. ``with testing.testConfig(...):``.
	728
64452e	729	- Users can now invoke a subrequest from within view code using a new
CM	730	``request.invoke_subrequest`` API.
37d2c2	731
2c2534	732	Deprecations
MM	733	------------
	734
9cdb28	735	- The ``pyramid.config.Configurator.set_request_property`` has been
CM	736	documentation-deprecated. The method remains usable but the more
023c88	737	featureful ``pyramid.config.Configurator.add_request_method`` should be
9cdb28	738	used in its place (it has all of the same capabilities but can also extend
CM	739	the request object with methods).
ebcdc7	740
CM	741	Backwards Incompatibilities
	742	---------------------------
	743
25d3dd	744	- The Pyramid router no longer adds the values ``bfg.routes.route`` or
ebcdc7	745	``bfg.routes.matchdict`` to the request's WSGI environment dictionary.
CM	746	These values were docs-deprecated in ``repoze.bfg`` 1.0 (effectively seven
	747	minor releases ago). If your code depended on these values, use
	748	request.matched_route and request.matchdict instead.
	749
	750	- It is no longer possible to pass an environ dictionary directly to
	751	``pyramid.traversal.ResourceTreeTraverser.__call__`` (aka
	752	``ModelGraphTraverser.__call__``). Instead, you must pass a request
	753	object. Passing an environment instead of a request has generated a
	754	deprecation warning since Pyramid 1.1.
	755
	756	- Pyramid will no longer work properly if you use the
	757	``webob.request.LegacyRequest`` as a request factory. Instances of the
	758	LegacyRequest class have a ``request.path_info`` which return a string.
	759	This Pyramid release assumes that ``request.path_info`` will
	760	unconditionally be Unicode.
	761
3d4272	762	- The functions from ``pyramid.chameleon_zpt`` and ``pyramid.chameleon_text``
CM	763	named ``get_renderer``, ``get_template``, ``render_template``, and
	764	``render_template_to_response`` have been removed. These have issued a
	765	deprecation warning upon import since Pyramid 1.0. Use
	766	``pyramid.renderers.get_renderer()``,
	767	``pyramid.renderers.get_renderer().implementation()``,
	768	``pyramid.renderers.render()`` or ``pyramid.renderers.render_to_response``
	769	respectively instead of these functions.
	770
94a6f3	771	- The ``pyramid.configuration`` module was removed. It had been deprecated
CM	772	since Pyramid 1.0 and printed a deprecation warning upon its use. Use
	773	``pyramid.config`` instead.
	774
b274d0	775	- The ``pyramid.paster.PyramidTemplate`` API was removed. It had been
CM	776	deprecated since Pyramid 1.1 and issued a warning on import. If your code
	777	depended on this, adjust your code to import
	778	``pyramid.scaffolds.PyramidTemplate`` instead.
	779
ef2e51	780	- The ``pyramid.settings.get_settings()`` API was removed. It had been
CM	781	printing a deprecation warning since Pyramid 1.0. If your code depended on
	782	this API, use ``pyramid.threadlocal.get_current_registry().settings``
	783	instead or use the ``settings`` attribute of the registry available from
	784	the request (``request.registry.settings``).
	785
69e0aa	786	- These APIs from the ``pyramid.testing`` module were removed. They have
CM	787	been printing deprecation warnings since Pyramid 1.0:
	788
	789	* ``registerDummySecurityPolicy``, use
	790	``pyramid.config.Configurator.testing_securitypolicy`` instead.
	791
	792	* ``registerResources`` (aka ``registerModels``, use
	793	``pyramid.config.Configurator.testing_resources`` instead.
	794
	795	* ``registerEventListener``, use
	796	``pyramid.config.Configurator.testing_add_subscriber`` instead.
	797
	798	* ``registerTemplateRenderer`` (aka `registerDummyRenderer``), use
	799	``pyramid.config.Configurator.testing_add_template`` instead.
	800
	801	* ``registerView``, use ``pyramid.config.Configurator.add_view`` instead.
	802
	803	* ``registerUtility``, use
	804	``pyramid.config.Configurator.registry.registerUtility`` instead.
	805
	806	* ``registerAdapter``, use
	807	``pyramid.config.Configurator.registry.registerAdapter`` instead.
	808
	809	* ``registerSubscriber``, use
	810	``pyramid.config.Configurator.add_subscriber`` instead.
	811
	812	* ``registerRoute``, use
	813	``pyramid.config.Configurator.add_route`` instead.
	814
	815	* ``registerSettings``, use
	816	``pyramid.config.Configurator.add_settings`` instead.
	817
64452e	818	- In Pyramid 1.3 and previous, the ``__call__`` method of a Response object
CM	819	was invoked before any finished callbacks were executed. As of this
	820	release, the ``__call__`` method of a Response object is invoked after
	821	finished callbacks are executed. This is in support of the
	822	``request.invoke_subrequest`` feature.
	823
b72ba1	824	Documentation
CM	825	-------------
	826
	827	- Added an "Upgrading Pyramid" chapter to the narrative documentation. It
07cb8f	828	describes how to cope with deprecations and removals of Pyramid APIs and
CM	829	how to show Pyramid-generated deprecation warnings while running tests and
	830	while running a server.
b72ba1	831
37d2c2	832	- Added a "Invoking a Subrequest" chapter to the documentation. It describes
64452e	833	how to use the new ``request.invoke_subrequest`` API.
37d2c2	834
ebcdc7	835	Dependencies
CM	836	------------
	837
	838	- Pyramid now requires WebOb 1.2b3+ (the prior Pyramid release only relied on
	839	1.2dev+). This is to ensure that we obtain a version of WebOb that returns
	840	``request.path_info`` as text.
	841