RedHatTraining/pyramid.git

Added the `pyramid.security.NO_PERMISSION_REQUIRED` constant.

Michael Merickel

2011-08-10 fecefff5f0c3a6aaafdd43d902aaed15edb8559e

commit \| author \| age
7de404	1	from zope.interface import Attribute
eca67a	2	from zope.interface import Interface
CM	3
4aa22c	4	# public API interfaces
CM	5
8f45be	6	class IContextFound(Interface):
fd5ae9	7	""" An event type that is emitted after :app:`Pyramid` finds a
8f45be	8	:term:`context` object but before it calls any view code. See the
c81aad	9	documentation attached to :class:`pyramid.events.ContextFound`
8f45be	10	for more information.
CM	11
	12	.. note:: For backwards compatibility with versions of
fd5ae9	13	:app:`Pyramid` before 1.0, this event interface can also be
c81aad	14	imported as :class:`pyramid.interfaces.IAfterTraversal`.
8f45be	15	"""
4aa22c	16	request = Attribute('The request object')
8f45be	17
CM	18	IAfterTraversal = IContextFound
4aa22c	19
CM	20	class INewRequest(Interface):
fd5ae9	21	""" An event type that is emitted whenever :app:`Pyramid`
8f45be	22	begins to process a new request. See the documentation attached
c81aad	23	to :class:`pyramid.events.NewRequest` for more information."""
4aa22c	24	request = Attribute('The request object')
CM	25
	26	class INewResponse(Interface):
fd5ae9	27	""" An event type that is emitted whenever any :app:`Pyramid`
8f45be	28	view returns a response. See the
c81aad	29	documentation attached to :class:`pyramid.events.NewResponse`
8f45be	30	for more information."""
eb7ea4	31	request = Attribute('The request object')
4aa22c	32	response = Attribute('The response object')
CM	33
8f45be	34	class IApplicationCreated(Interface):
c6895b	35	""" Event issued when the
aff443	36	:meth:`pyramid.config.Configurator.make_wsgi_app` method
8f45be	37	is called. See the documentation attached to
c81aad	38	:class:`pyramid.events.ApplicationCreated` for more
8f45be	39	information.
CM	40
fd5ae9	41	.. note:: For backwards compatibility with :app:`Pyramid`
c81aad	42	versions before 1.0, this interface can also be imported as
CM	43	:class:`pyramid.interfaces.IWSGIApplicationCreatedEvent`.
8f45be	44	"""
239a93	45	app = Attribute(u"Created application")
CM	46
	47	IWSGIApplicationCreatedEvent = IApplicationCreated # b /c
4aa22c	48
99edc5	49	class IResponse(Interface):
51fb07	50	""" Represents a WSGI response using the WebOb response interface. Some
CM	51	attribute and method documentation of this interface references `RFC 2616
	52	<http://www.w3.org/Protocols/rfc2616/>`_.
	53
	54	This interface is most famously implemented by
	55	:class:`pyramid.response.Response` and the HTTP exception classes in
	56	:mod:`pyramid.httpexceptions`."""
	57
	58	RequestClass = Attribute(
	59	""" Alias for :class:`pyramid.request.Request` """)
99edc5	60
CM	61	def __call__(environ, start_response):
51fb07	62	""" :term:`WSGI` call interface, should call the start_response
CM	63	callback and should return an iterable"""
	64
	65	accept_ranges = Attribute(
	66	"""Gets and sets and deletes the Accept-Ranges header. For more
	67	information on Accept-Ranges see RFC 2616, section 14.5""")
	68
	69	age = Attribute(
	70	"""Gets and sets and deletes the Age header. Converts using int.
	71	For more information on Age see RFC 2616, section 14.6.""")
	72
	73	allow = Attribute(
	74	"""Gets and sets and deletes the Allow header. Converts using
	75	list. For more information on Allow see RFC 2616, Section 14.7.""")
	76
	77	app_iter = Attribute(
	78	"""Returns the app_iter of the response.
	79
	80	If body was set, this will create an app_iter from that body
	81	(a single-item list)""")
	82
	83	def app_iter_range(start, stop):
	84	""" Return a new app_iter built from the response app_iter that
	85	serves up only the given start:stop range. """
	86
	87	body = Attribute(
	88	"""The body of the response, as a str. This will read in the entire
	89	app_iter if necessary.""")
	90
	91	body_file = Attribute(
	92	"""A file-like object that can be used to write to the body. If you
	93	passed in a list app_iter, that app_iter will be modified by writes.""")
	94
	95	cache_control = Attribute(
	96	"""Get/set/modify the Cache-Control header (RFC 2616 section 14.9)""")
	97
	98	cache_expires = Attribute(
	99	""" Get/set the Cache-Control and Expires headers. This sets the
	100	response to expire in the number of seconds passed when set. """)
	101
	102	charset = Attribute(
	103	"""Get/set the charset (in the Content-Type)""")
	104
	105	def conditional_response_app(environ, start_response):
	106	""" Like the normal __call__ interface, but checks conditional
	107	headers:
	108
	109	- If-Modified-Since (304 Not Modified; only on GET, HEAD)
	110
	111	- If-None-Match (304 Not Modified; only on GET, HEAD)
	112
	113	- Range (406 Partial Content; only on GET, HEAD)"""
	114
	115	content_disposition = Attribute(
	116	"""Gets and sets and deletes the Content-Disposition header.
	117	For more information on Content-Disposition see RFC 2616 section
	118	19.5.1.""")
	119
	120	content_encoding = Attribute(
	121	"""Gets and sets and deletes the Content-Encoding header. For more
	122	information about Content-Encoding see RFC 2616 section 14.11.""")
	123
	124	content_language = Attribute(
	125	"""Gets and sets and deletes the Content-Language header. Converts
	126	using list. For more information about Content-Language see RFC 2616
	127	section 14.12.""")
	128
	129	content_length = Attribute(
	130	"""Gets and sets and deletes the Content-Length header. For more
	131	information on Content-Length see RFC 2616 section 14.17.
	132	Converts using int. """)
	133
	134	content_location = Attribute(
	135	"""Gets and sets and deletes the Content-Location header. For more
	136	information on Content-Location see RFC 2616 section 14.14.""")
	137
	138	content_md5 = Attribute(
	139	"""Gets and sets and deletes the Content-MD5 header. For more
	140	information on Content-MD5 see RFC 2616 section 14.14.""")
	141
	142	content_range = Attribute(
	143	"""Gets and sets and deletes the Content-Range header. For more
	144	information on Content-Range see section 14.16. Converts using
	145	ContentRange object.""")
	146
	147	content_type = Attribute(
	148	"""Get/set the Content-Type header (or None), without the charset
	149	or any parameters. If you include parameters (or ; at all) when
	150	setting the content_type, any existing parameters will be deleted;
	151	otherwise they will be preserved.""")
	152
	153	content_type_params = Attribute(
	154	"""A dictionary of all the parameters in the content type. This is
	155	not a view, set to change, modifications of the dict would not
	156	be applied otherwise.""")
	157
	158	def copy():
	159	""" Makes a copy of the response and returns the copy. """
	160
	161	date = Attribute(
	162	"""Gets and sets and deletes the Date header. For more information on
	163	Date see RFC 2616 section 14.18. Converts using HTTP date.""")
	164
	165	def delete_cookie(key, path='/', domain=None):
	166	""" Delete a cookie from the client. Note that path and domain must
	167	match how the cookie was originally set. This sets the cookie to the
	168	empty string, and max_age=0 so that it should expire immediately. """
	169
	170	def encode_content(encoding='gzip', lazy=False):
	171	""" Encode the content with the given encoding (only gzip and
	172	identity are supported)."""
	173
	174	environ = Attribute(
	175	"""Get/set the request environ associated with this response,
	176	if any.""")
	177
	178	etag = Attribute(
	179	""" Gets and sets and deletes the ETag header. For more information
	180	on ETag see RFC 2616 section 14.19. Converts using Entity tag.""")
	181
	182	expires = Attribute(
	183	""" Gets and sets and deletes the Expires header. For more
	184	information on Expires see RFC 2616 section 14.21. Converts using
	185	HTTP date.""")
	186
	187	headerlist = Attribute(
	188	""" The list of response headers. """)
	189
	190	headers = Attribute(
	191	""" The headers in a dictionary-like object """)
	192
	193	last_modified = Attribute(
	194	""" Gets and sets and deletes the Last-Modified header. For more
	195	information on Last-Modified see RFC 2616 section 14.29. Converts
	196	using HTTP date.""")
	197
	198	location = Attribute(
	199	""" Gets and sets and deletes the Location header. For more
	200	information on Location see RFC 2616 section 14.30.""")
	201
	202	def md5_etag(body=None, set_content_md5=False):
	203	""" Generate an etag for the response object using an MD5 hash of the
	204	body (the body parameter, or self.body if not given). Sets self.etag.
	205	If set_content_md5 is True sets self.content_md5 as well """
	206
	207	def merge_cookies(resp):
	208	""" Merge the cookies that were set on this response with the given
	209	resp object (which can be any WSGI application). If the resp is a
	210	webob.Response object, then the other object will be modified
	211	in-place. """
	212
	213	pragma = Attribute(
	214	""" Gets and sets and deletes the Pragma header. For more information
	215	on Pragma see RFC 2616 section 14.32. """)
	216
	217	request = Attribute(
	218	""" Return the request associated with this response if any. """)
	219
	220	retry_after = Attribute(
	221	""" Gets and sets and deletes the Retry-After header. For more
	222	information on Retry-After see RFC 2616 section 14.37. Converts
	223	using HTTP date or delta seconds.""")
	224
	225	server = Attribute(
	226	""" Gets and sets and deletes the Server header. For more information
	227	on Server see RFC216 section 14.38. """)
	228
	229	def set_cookie(key, value='', max_age=None, path='/', domain=None,
	230	secure=False, httponly=False, comment=None, expires=None,
	231	overwrite=False):
	232	""" Set (add) a cookie for the response """
	233
	234	status = Attribute(
	235	""" The status string. """)
	236
	237	status_int = Attribute(
	238	""" The status as an integer """)
	239
	240	unicode_body = Attribute(
	241	""" Get/set the unicode value of the body (using the charset of
	242	the Content-Type)""")
	243
	244	def unset_cookie(key, strict=True):
	245	""" Unset a cookie with the given name (remove it from the
	246	response)."""
	247
	248	vary = Attribute(
	249	"""Gets and sets and deletes the Vary header. For more information
	250	on Vary see section 14.44. Converts using list.""")
	251
	252	www_authenticate = Attribute(
	253	""" Gets and sets and deletes the WWW-Authenticate header. For more
	254	information on WWW-Authenticate see RFC 2616 section 14.47. Converts
	255	using 'parse_auth' and 'serialize_auth'. """)
d96ff9	256
CM	257	class IException(Interface): # not an API
	258	""" An interface representing a generic exception """
	259
	260	class IExceptionResponse(IException, IResponse):
a7e625	261	""" An interface representing a WSGI response which is also an exception
CM	262	object. Register an exception view using this interface as a ``context``
	263	to apply the registered view for all exception types raised by
	264	:app:`Pyramid` internally (any exception that inherits from
	265	:class:`pyramid.response.Response`, including
99edc5	266	:class:`pyramid.httpexceptions.HTTPNotFound` and
CM	267	:class:`pyramid.httpexceptions.HTTPForbidden`)."""
d96ff9	268
a76e99	269	class IBeforeRender(Interface):
CM	270	"""
	271	Subscribers to this event may introspect the and modify the set of
	272	:term:`renderer globals` before they are passed to a :term:`renderer`.
	273	This event object iself has a dictionary-like interface that can be used
	274	for this purpose. For example::
	275
	276	from repoze.events import subscriber
	277	from pyramid.interfaces import IBeforeRender
	278
	279	@subscriber(IBeforeRender)
	280	def add_global(event):
	281	event['mykey'] = 'foo'
	282
	283	See also :ref:`beforerender_event`.
	284	"""
	285	def __setitem__(name, value):
	286	""" Set a name/value pair into the dictionary which is passed to a
82efa4	287	renderer as the renderer globals dictionary. """
CM	288
	289	def setdefault(name, default=None):
	290	""" Return the existing value for ``name`` in the renderers globals
	291	dictionary. If no value with ``name`` exists in the dictionary, set
	292	the ``default`` value into the renderer globals dictionary under the
	293	name passed. If a value already existed in the dictionary, return
	294	it. If a value did not exist in the dictionary, return the default"""
a76e99	295
CM	296	def update(d):
	297	""" Update the renderer globals dictionary with another dictionary
82efa4	298	``d``. """
a76e99	299
CM	300	def __contains__(k):
	301	""" Return ``True`` if ``k`` exists in the renderer globals
	302	dictionary."""
	303
	304	def __getitem__(k):
	305	""" Return the value for key ``k`` from the renderer globals
	306	dictionary."""
	307
	308	def get(k, default=None):
	309	""" Return the value for key ``k`` from the renderer globals
	310	dictionary, or the default if no such value exists."""
	311
9a66aa	312	rendering_val = Attribute('The value returned by a view or passed to a '
CM	313	'``render`` method for this rendering. '
	314	'This feature is new in Pyramid 1.1.1.')
	315
e26903	316	class IRenderer(Interface):
CM	317	def __call__(value, system):
	318	""" Call a the renderer implementation with the result of the
	319	view (``value``) passed in and return a result (a string or
	320	unicode object useful as a response body). Values computed by
	321	the system are passed by the system in the ``system``
	322	parameter, which is a dictionary. Keys in the dictionary
	323	include: ``view`` (the view callable that returned the value),
	324	``renderer_name`` (the template name or simple name of the
	325	renderer), ``context`` (the context object passed to the
	326	view), and ``request`` (the request object passed to the
	327	view)."""
	328
	329	class ITemplateRenderer(IRenderer):
	330	def implementation():
	331	""" Return the object that the underlying templating system
	332	uses to render the template; it is typically a callable that
	333	accepts arbitrary keyword arguments and returns a string or
	334	unicode object """
	335
8739f5	336	class IViewMapper(Interface):
CM	337	def __call__(self, object):
	338	""" Provided with an arbitrary object (a function, class, or
	339	instance), returns a callable with the call signature ``(context,
	340	request)``. The callable returned should itself return a Response
	341	object. An IViewMapper is returned by
	342	:class:`pyramid.interfaces.IViewMapperFactory`."""
	343
	344	class IViewMapperFactory(Interface):
	345	def __call__(self, **kw):
	346	"""
	347	Return an object which implements
	348	:class:`pyramid.interfaces.IViewMapper`. ``kw`` will be a dictionary
	349	containing view-specific arguments, such as ``permission``,
	350	``predicates``, ``attr``, ``renderer``, and other items. An
	351	IViewMapperFactory is used by
	352	:meth:`pyramid.config.Configurator.add_view` to provide a plugpoint
	353	to extension developers who want to modify potential view callable
	354	invocation signatures and response values.
	355	"""
	356
4aa22c	357	class IAuthenticationPolicy(Interface):
c81aad	358	""" An object representing a Pyramid authentication policy. """
4aa22c	359	def authenticated_userid(request):
2526d8	360	""" Return the authenticated userid or ``None`` if no authenticated
CM	361	userid can be found. This method of the policy should ensure that a
	362	record exists in whatever persistent store is used related to the
	363	user (the user should not have been deleted); if a record associated
	364	with the current id does not exist in a persistent store, it should
	365	return ``None``."""
	366
	367	def unauthenticated_userid(request):
	368	""" Return the unauthenticated userid. This method performs the
	369	same duty as ``authenticated_userid`` but is permitted to return the
39eb94	370	userid based only on data present in the request; it needn't (and
2526d8	371	shouldn't) check any persistent store to ensure that the user record
CM	372	related to the request userid exists."""
4aa22c	373
CM	374	def effective_principals(request):
	375	""" Return a sequence representing the effective principals
	376	including the userid and any groups belonged to by the current
	377	user, including 'system' groups such as Everyone and
	378	Authenticated. """
	379
	380	def remember(request, principal, **kw):
	381	""" Return a set of headers suitable for 'remembering' the
	382	principal named ``principal`` when set in a response. An
	383	individual authentication policy and its consumers can decide
d2973d	384	on the composition and meaning of ``**kw.`` """
4aa22c	385
CM	386	def forget(request):
	387	""" Return a set of headers suitable for 'forgetting' the
	388	current user on subsequent requests. """
	389
	390	class IAuthorizationPolicy(Interface):
c81aad	391	""" An object representing a Pyramid authorization policy. """
4aa22c	392	def permits(context, principals, permission):
57cc86	393	""" Return ``True`` if any of the ``principals`` is allowed the
CM	394	``permission`` in the current ``context``, else return ``False``
	395	"""
4aa22c	396
CM	397	def principals_allowed_by_permission(context, permission):
57cc86	398	""" Return a set of principal identifiers allowed by the
CM	399	``permission`` in ``context``. This behavior is optional; if you
	400	choose to not implement it you should define this method as
	401	something which raises a ``NotImplementedError``. This method
	402	will only be called when the
	403	``pyramid.security.principals_allowed_by_permission`` API is
	404	used."""
4aa22c	405
2a1c3f	406	class IMultiDict(Interface): # docs-only interface
CM	407	"""
	408	An ordered dictionary that can have multiple values for each key. A
	409	multidict adds the methods ``getall``, ``getone``, ``mixed``, ``extend``
	410	``add``, and ``dict_of_lists`` to the normal dictionary interface. A
	411	multidict data structure is used as ``request.POST``, ``request.GET``,
	412	and ``request.params`` within an :app:`Pyramid` application.
	413	"""
	414
	415	def add(key, value):
	416	""" Add the key and value, not overwriting any previous value. """
	417
	418	def dict_of_lists():
	419	"""
	420	Returns a dictionary where each key is associated with a list of
	421	values.
	422	"""
	423
	424	def extend(other=None, **kwargs):
	425	""" Add a set of keys and values, not overwriting any previous
	426	values. The ``other`` structure may be a list of two-tuples or a
	427	dictionary. If ``*kwargs`` is passed, its value will* overwrite
	428	existing values."""
	429
	430	def getall(key):
	431	""" Return a list of all values matching the key (may be an empty
	432	list) """
	433
	434	def getone(key):
	435	""" Get one value matching the key, raising a KeyError if multiple
	436	values were found. """
	437
	438	def mixed():
	439	""" Returns a dictionary where the values are either single values,
	440	or a list of values when a key/value appears more than once in this
	441	dictionary. This is similar to the kind of dictionary often used to
	442	represent the variables in a web request. """
d2973d	443
CM	444	# internal interfaces
	445
	446	class IRequest(Interface):
	447	""" Request type interface attached to all request objects """
	448
b4843b	449	class ITweens(Interface):
af2323	450	""" Marker interface for utility registration representing the ordered
b4843b	451	set of a configuration's tween factories"""
af2323	452
CM	453	class IRequestHandler(Interface):
	454	""" """
	455	def __call__(self, request):
0d4963	456	""" Must return a tuple of IReqest, IResponse or raise an exception.
CM	457	The ``request`` argument will be an instance of an object that
	458	provides IRequest."""
af2323	459
d2973d	460	IRequest.combined = IRequest # for exception view lookups
CM	461
	462	class IRouteRequest(Interface):
	463	""" internal only interface used as in a utility lookup to find
	464	route-specific interfaces. Not an API."""
	465
b29429	466	class IStaticURLInfo(Interface):
3e2f12	467	""" A policy for generating URLs to static assets """
b29429	468	def add(name, spec, **extra):
CM	469	""" Add a new static info registration """
	470
	471	def generate(path, request, **kw):
	472	""" Generate a URL for the given path """
a0b40c	473
c8cf22	474	class IResponseFactory(Interface):
CM	475	""" A utility which generates a response factory """
3e7be7	476	def __call__():
94b889	477	""" Return a response factory (e.g. a callable that returns an object
CM	478	implementing IResponse, e.g. :class:`pyramid.response.Response`). It
	479	should accept all the arguments that the Pyramid Response class
	480	accepts."""
7de404	481
81a833	482	class IRequestFactory(Interface):
CM	483	""" A utility which generates a request """
	484	def __call__(environ):
	485	""" Return an object implementing IRequest, e.g. an instance
c81aad	486	of ``pyramid.request.Request``"""
81a833	487
CM	488	def blank(path):
	489	""" Return an empty request object (see
8c6a4c	490	:meth:`pyramid.request.Request.blank`)"""
81a833	491
ff1213	492	class IViewClassifier(Interface):
CM	493	""" Internal only marker interface for views."""
	494
	495	class IExceptionViewClassifier(Interface):
	496	""" Internal only marker interface for exception views."""
	497
7de404	498	class IView(Interface):
CM	499	def __call__(context, request):
99edc5	500	""" Must return an object that implements IResponse. """
d66bfb	501
CM	502	class ISecuredView(IView):
573184	503	""" Internal only interface. Not an API. """
d66bfb	504	def __call_permissive__(context, request):
CM	505	""" Guaranteed-permissive version of __call__ """
	506
	507	def __permitted__(context, request):
	508	""" Return True if view execution will be permitted using the
	509	context and request, False otherwise"""
	510
	511	class IMultiView(ISecuredView):
	512	""" internal only. A multiview is a secured view that is a
	513	collection of other views. Each of the views is associated with
	514	zero or more predicates. Not an API."""
ff1213	515	def add(view, predicates, order, accept=None, phash=None):
d66bfb	516	""" Add a view to the multiview. """
5ed24b	517
358dc2	518	class IRootFactory(Interface):
8b1f6e	519	def __call__(request):
CM	520	""" Return a root object based on the request """
dfc2b6	521
CM	522	class IDefaultRootFactory(Interface):
8b1f6e	523	def __call__(request):
dfc2b6	524	""" Return the default root object for an application """
612d74	525
4df575	526	class ITraverser(Interface):
8b1f6e	527	def __call__(request):
80a25e	528	""" Return a dictionary with (at least) the keys ``root``,
CM	529	``context``, ``view_name``, ``subpath``, ``traversed``,
	530	``virtual_root``, and ``virtual_root_path``. These values are
f426e5	531	typically the result of an object graph traversal. ``root`` is the
CM	532	physical root object, ``context`` will be a model object,
	533	``view_name`` will be the view name used (a Unicode name),
	534	``subpath`` will be a sequence of Unicode names that followed the
	535	view name but were not traversed, ``traversed`` will be a sequence of
	536	Unicode names that were traversed (including the virtual root path,
	537	if any) ``virtual_root`` will be a model object representing the
	538	virtual root (or the physical root if traversal was not performed),
	539	and ``virtual_root_path`` will be a sequence representing the virtual
	540	root path (a sequence of Unicode names) or ``None`` if traversal was
	541	not performed.
80a25e	542
f426e5	543	Extra keys for special purpose functionality can be returned as
80a25e	544	necessary.
CM	545
	546	All values returned in the dictionary will be made available
f426e5	547	as attributes of the ``request`` object by the :term:`router`.
80a25e	548	"""
93a4f5	549
517d03	550	ITraverserFactory = ITraverser # b / c for 1.0 code
8f8869	551
a9fed7	552	class IRendererFactory(Interface):
fe6c8d	553	def __call__(info):
CM	554	""" Return an object that implements ``IRenderer``. ``info`` is an
	555	object that implement ``IRendererInfo``. """
a9fed7	556
250c02	557	class IRendererGlobalsFactory(Interface):
CM	558	def __call__(system_values):
	559	""" Return a dictionary of global renderer values (aka
	560	top-level template names). The ``system_values`` value passed
	561	in will be a dictionary that includes at least a ``request``
	562	key, indicating the current request, and the value
	563	``renderer_name``, which will be the name of the renderer in
	564	use."""
4df575	565
2466f6	566	class IViewPermission(Interface):
d7e43b	567	def __call__(context, request):
2466f6	568	""" Return True if the permission allows, return False if it denies. """
CM	569
eba6f8	570	class IRouter(Interface):
MB	571	"""WSGI application which routes requests to 'view' code based on
	572	a view registry."""
9dd823	573	registry = Attribute(
eba6f8	574	"""Component architecture registry local to this application.""")
MB	575
0e21c2	576	class ISettings(Interface):
c81aad	577	""" Runtime settings utility for pyramid; represents the
8b1f6e	578	deployment settings for the application. Implements a mapping
CM	579	interface."""
0e21c2	580
c81aad	581	# this interface, even if it becomes unused within Pyramid, is
cba2e1	582	# imported by other packages (such as traversalwrapper)
cbdc36	583	class ILocation(Interface):
CM	584	"""Objects that have a structural location"""
	585	__parent__ = Attribute("The parent in the location hierarchy")
	586	__name__ = Attribute("The name within the parent")
	587
bd39b1	588	class IDebugLogger(Interface):
47b4d3	589	""" Interface representing a PEP 282 logger """
62267e	590
bd39b1	591	ILogger = IDebugLogger # b/c
CM	592
70f1cd	593	class IRoutePregenerator(Interface):
CM	594	def __call__(request, elements, kw):
	595	""" A pregenerator is a function associated by a developer
	596	with a :term:`route`. The pregenerator for a route is called
c81aad	597	by :func:`pyramid.url.route_url` in order to adjust the set
70f1cd	598	of arguments passed to it by the user for special purposes,
CM	599	such as Pylons 'subdomain' support. It will influence the URL
	600	returned by ``route_url``.
	601
	602	A pregenerator should return a two-tuple of ``(elements, kw)``
	603	after examining the originals passed to this function, which
	604	are the arguments ``(request, elements, kw)``. The simplest
	605	pregenerator is::
	606
	607	def pregenerator(request, elements, kw):
	608	return elements, kw
	609
	610	You can employ a pregenerator by passing a ``pregenerator``
	611	argument to the
aff443	612	:meth:`pyramid.config.Configurator.add_route`
70f1cd	613	function.
CM	614
	615	"""
	616
74409d	617	class IRoute(Interface):
CM	618	""" Interface representing the type of object returned from
	619	``IRoutesMapper.get_route``"""
	620	name = Attribute('The route name')
	621	pattern = Attribute('The route pattern')
	622	factory = Attribute(
fd5ae9	623	'The :term:`root factory` used by the :app:`Pyramid` router '
74409d	624	'when this route matches (or ``None``)')
CM	625	predicates = Attribute(
	626	'A sequence of :term:`route predicate` objects used to '
c337a8	627	'determine if a request matches this route or not after '
74409d	628	'basic pattern matching has been completed.')
70f1cd	629	pregenerator = Attribute('This attribute should either be ``None`` or '
CM	630	'a callable object implementing the '
	631	'``IRoutePregenerator`` interface')
74409d	632	def match(path):
CM	633	"""
	634	If the ``path`` passed to this function can be matched by the
	635	``pattern`` of this route, return a dictionary (the
	636	'matchdict'), which will contain keys representing the dynamic
	637	segment markers in the pattern mapped to values extracted from
	638	the provided ``path``.
	639
	640	If the ``path`` passed to this function cannot be matched by
	641	the ``pattern`` of this route, return ``None``.
	642	"""
	643	def generate(kw):
	644	"""
	645	Generate a URL based on filling in the dynamic segment markers
	646	in the pattern using the ``kw`` dictionary provided.
	647	"""
	648
62267e	649	class IRoutesMapper(Interface):
CM	650	""" Interface representing a Routes ``Mapper`` object """
8b1f6e	651	def get_routes():
e725cf	652	""" Return a sequence of Route objects registered in the mapper.
CM	653	Static routes will not be returned in this sequence."""
8b1f6e	654
74409d	655	def has_routes():
CM	656	""" Returns ``True`` if any route has been registered. """
	657
	658	def get_route(name):
	659	""" Returns an ``IRoute`` object if a route with the name ``name``
	660	was registered, otherwise return ``None``."""
	661
90ed75	662	def connect(name, pattern, factory=None, predicates=(), pregenerator=None,
CM	663	static=True):
8b1f6e	664	""" Add a new route. """
CM	665
	666	def generate(name, kw):
	667	""" Generate a URL using the route named ``name`` with the
	668	keywords implied by kw"""
	669
	670	def __call__(request):
74409d	671	""" Return a dictionary containing matching information for
CM	672	the request; the ``route`` key of this dictionary will either
	673	be a Route object or ``None`` if no route matched; the
51b2f9	674	``match`` key will be the matchdict or ``None`` if no route
90ed75	675	matched. Static routes will not be considered for matching. """
8b1f6e	676
e62e47	677	class IContextURL(Interface):
CM	678	""" An adapter which deals with URLs related to a context.
925957	679	"""
e62e47	680	def virtual_root():
CM	681	""" Return the virtual root related to a request and the
	682	current context"""
	683
	684	def __call__():
	685	""" Return a URL that points to the context """
05c023	686
2869fc	687	class IPackageOverrides(Interface):
CM	688	""" Utility for pkg_resources overrides """
	689
a7a6d7	690	# VH_ROOT_KEY is an interface; its imported from other packages (e.g.
CM	691	# traversalwrapper)
ff1213	692	VH_ROOT_KEY = 'HTTP_X_VHM_ROOT'
7534ba	693
7b8d65	694	class IChameleonLookup(Interface):
CM	695	translate = Attribute('IChameleonTranslate object')
	696	debug = Attribute('The ``debug_templates`` setting for this application')
	697	auto_reload = Attribute('The ``reload_templates`` setting for this app')
	698	def __call__(self, info):
	699	""" Return an ITemplateRenderer based on IRendererInfo ``info`` """
	700
7534ba	701	class IChameleonTranslate(Interface):
CM	702	""" Internal interface representing a chameleon translate function """
	703	def __call__(msgid, domain=None, mapping=None, context=None,
	704	target_language=None, default=None):
	705	""" Translate a mess of arguments to a Unicode object """
	706
	707	class ILocalizer(Interface):
	708	""" Localizer for a specific language """
	709
	710	class ILocaleNegotiator(Interface):
	711	def __call__(request):
	712	""" Return a locale name """
	713
	714	class ITranslationDirectories(Interface):
	715	""" A list object representing all known translation directories
	716	for an application"""
d96ff9	717
e25a70	718	class IDefaultPermission(Interface):
CM	719	""" A string object representing the default permission to be used
	720	for all view configurations which do not explicitly declare their
	721	own."""
968209	722
CM	723	class ISessionFactory(Interface):
	724	""" An interface representing a factory which accepts a request object and
	725	returns an ISession object """
	726	def __call__(request):
	727	""" Return an ISession object """
	728
	729	class ISession(Interface):
	730	""" An interface representing a session (a web session object,
	731	usually accessed via ``request.session``.
	732
	733	Keys and values of a session must be pickleable.
	734	"""
	735
	736	# attributes
	737
	738	created = Attribute('Integer representing Epoch time when created.')
	739	new = Attribute('Boolean attribute. If ``True``, the session is new.')
	740
	741	# special methods
	742
	743	def invalidate():
	744	""" Invalidate the session. The action caused by
	745	``invalidate`` is implementation-dependent, but it should have
	746	the effect of completely dissociating any data stored in the
	747	session with the current request. It might set response
	748	values (such as one which clears a cookie), or it might not."""
	749
	750	def changed():
	751	""" Mark the session as changed. A user of a session should
	752	call this method after he or she mutates a mutable object that
	753	is a value of the session (it should not be required after
	754	mutating the session itself). For example, if the user has
	755	stored a dictionary in the session under the key ``foo``, and
	756	he or she does ``session['foo'] = {}``, ``changed()`` needn't
	757	be called. However, if subsequently he or she does
	758	``session['foo']['a'] = 1``, ``changed()`` must be called for
	759	the sessioning machinery to notice the mutation of the
	760	internal dictionary."""
	761
6f6d36	762	def flash(msg, queue='', allow_duplicate=True):
CM	763	""" Push a flash message onto the end of the flash queue represented
	764	by ``queue``. An alternate flash message queue can used by passing
	765	an optional ``queue``, which must be a string. If
	766	``allow_duplicate`` is false, if the ``msg`` already exists in the
	767	queue, it will not be readded."""
4df636	768
6f6d36	769	def pop_flash(queue=''):
CM	770	""" Pop a queue from the flash storage. The queue is removed from
	771	flash storage after this message is called. The queue is returned;
	772	it is a list of flash messages added by
be03f7	773	:meth:`pyramid.interfaces.ISession.flash`"""
6f6d36	774
CM	775	def peek_flash(queue=''):
	776	""" Peek at a queue in the flash storage. The queue remains in
	777	flash storage after this message is called. The queue is returned;
	778	it is a list of flash messages added by
be03f7	779	:meth:`pyramid.interfaces.ISession.flash`
319793	780	"""
CM	781
ac718c	782	def new_csrf_token():
319793	783	""" Create and set into the session a new, random cross-site request
CM	784	forgery protection token. Return the token. It will be a string."""
	785
ac718c	786	def get_csrf_token():
14f863	787	""" Return a random cross-site request forgery protection token. It
CM	788	will be a string. If a token was previously added to the session via
	789	``new_csrf_token``, that token will be returned. If no CSRF token
	790	was previously set into the session, ``new_csrf_token`` will be
	791	called, which will create and set a token, and this token will be
	792	returned.
319793	793	"""
4df636	794
968209	795	# mapping methods
e25a70	796
968209	797	def __getitem__(key):
CM	798	"""Get a value for a key
	799
04ebd5	800	A ``KeyError`` is raised if there is no value for the key.
968209	801	"""
CM	802
	803	def get(key, default=None):
	804	"""Get a value for a key
	805
	806	The default is returned if there is no value for the key.
	807	"""
	808
	809	def __delitem__(key):
	810	"""Delete a value from the mapping using the key.
	811
04ebd5	812	A ``KeyError`` is raised if there is no value for the key.
968209	813	"""
CM	814
	815	def __setitem__(key, value):
	816	"""Set a new item in the mapping."""
	817
	818	def keys():
	819	"""Return the keys of the mapping object.
	820	"""
	821
	822	def values():
	823	"""Return the values of the mapping object.
	824	"""
	825
	826	def items():
	827	"""Return the items of the mapping object.
	828	"""
	829
	830	def iterkeys():
	831	"iterate over keys; equivalent to __iter__"
	832
	833	def itervalues():
	834	"iterate over values"
	835
	836	def iteritems():
	837	"iterate over items"
	838
	839	def clear():
	840	"delete all items"
	841
	842	def update(d):
	843	" Update D from E: for k in E.keys(): D[k] = E[k]"
	844
	845	def setdefault(key, default=None):
04ebd5	846	" D.setdefault(k[,d]) -> D.get(k,d), also set D[k]=d if k not in D "
968209	847
CM	848	def pop(k, *args):
	849	"""remove specified key and return the corresponding value
04ebd5	850	``*args`` may contain a single default value, or may not be supplied.
968209	851	If key is not found, default is returned if given, otherwise
04ebd5	852	``KeyError`` is raised"""
968209	853
CM	854	def popitem():
	855	"""remove and return some (key, value) pair as a
04ebd5	856	2-tuple; but raise ``KeyError`` if mapping is empty"""
968209	857
CM	858	def __len__():
	859	"""Return the number of items in the session.
	860	"""
	861
	862	def __iter__():
	863	"""Return an iterator for the keys of the mapping object.
	864	"""
	865
	866	def __contains__(key):
	867	"""Return true if a key exists in the mapping."""
	868
3a2af3	869	class IRendererInfo(Interface):
ba471c	870	""" An object implementing this interface is passed to every
CM	871	:term:`renderer factory` constructor as its only argument (conventionally
	872	named ``info``)"""
3a2af3	873	name = Attribute('The value passed by the user as the renderer name')
CM	874	package = Attribute('The "current package" when the renderer '
	875	'configuration statement was found')
	876	type = Attribute('The renderer type name')
	877	registry = Attribute('The "current" application registry when the '
	878	'renderer was created')
63ddb0	879	settings = Attribute('The deployment settings dictionary related '
CM	880	'to the current application')
3a2af3	881