Файл: pyramid.pdf

CHAPTER

FIFTYSIX

PYRAMID.SCRIPTING

get_root(app, request=None)

Return a tuple composed of (root, closer) when provided a router instance as the app argument. The root returned is the application root object. The closer returned is a callable (accepting no arguments) that should be called when your scripting application is finished using the root.

request is passed to the Pyramid application root factory to compute the root. If request is None, a default will be constructed using the registry’s Request Factory via the pyramid.interfaces.IRequestFactory.blank() method.

prepare(request=None, registry=None)

This function pushes data onto the Pyramid threadlocal stack (request and registry), making those objects ‘current’. It returns a dictionary useful for bootstrapping a Pyramid application in a scripting environment.

request is passed to the Pyramid application root factory to compute the root. If request is None, a default will be constructed using the registry’s Request Factory via the pyramid.interfaces.IRequestFactory.blank() method.

If registry is not supplied, the last registry loaded from pyramid.config.global_registries will be used. If you have loaded more than one Pyramid application in the current process, you may not want to use the last registry loaded, thus you can search the global_registries and supply the appropriate one based on your own criteria.

The function returns a dictionary composed of root, closer, registry, request and root_factory. The root returned is the application’s root resource object. The closer returned is a callable (accepting no arguments) that should be called when your scripting application is finished using the root. registry is the registry object passed or the last registry loaded into pyramid.config.global_registries if no registry is passed. request is the request object passed or the constructed request if no request is passed. root_factory is the root factory used to construct the root.

649

56. PYRAMID.SCRIPTING

650

CHAPTER

FIFTYSEVEN

PYRAMID.SECURITY

57.1 Authentication API Functions

authenticated_userid(request)

Return the userid of the currently authenticated user or None if there is no authentication policy in effect or there is no currently authenticated user.

unauthenticated_userid(request)

Return an object which represents the claimed (not verified) user id of the credentials present in the request. None if there is no authentication policy in effect or there is no user data associated with the current request. This differs from authenticated_userid(), because the effective authentication policy will not ensure that a record associated with the userid exists in persistent storage.

effective_principals(request)

Return the list of ‘effective’ principal identifiers for the request. This will include the userid of the currently authenticated user if a user is currently authenticated. If no authentication policy is in effect, this will return an empty sequence.

forget(request)

Return a sequence of header tuples (e.g. [(’Set-Cookie’, ’foo=abc’)]) suitable for ‘forgetting’ the set of credentials possessed by the currently authenticated user. A common usage might look like so within the body of a view function (response is assumed to be an WebOb -style response object computed previously by the view code):

651

57. PYRAMID.SECURITY

from pyramid.security import forget headers = forget(request) response.headerlist.extend(headers) return response

If no authentication policy is in use, this function will always return an empty sequence.

remember(request, principal, **kw)

Return a sequence of header tuples (e.g. [(’Set-Cookie’, ’foo=abc’)]) suitable for ‘remembering’ a set of credentials implied by the data passed as principal and *kw using the current authentication policy. Common usage might look like so within the body of a view function (response is assumed to be a WebOb -style response object computed previously by the view code):

from pyramid.security import remember

headers = remember(request, ’chrism’, password=’123’, max_age=’86400’) response.headerlist.extend(headers)

return response

If no authentication policy is in use, this function will always return an empty sequence. If used, the composition and meaning of **kw must be agreed upon by the calling code and the effective authentication policy.

57.2 Authorization API Functions

has_permission(permission, context, request)

Provided a permission (a string or unicode object), a context (a resource instance) and a request object, return an instance of pyramid.security.Allowed if the permission is granted in this context to the user implied by the request. Return an instance of pyramid.security.Denied if this permission is not granted in this context to this user. This function delegates to the current authentication and authorization policies. Return pyramid.security.Allowed unconditionally if no authentication policy has been configured in this application.

principals_allowed_by_permission(context, permission)

Provided a context (a resource object), and a permission (a string or unicode object), if a authorization policy is in effect, return a sequence of principal ids that possess the permission in the context. If no authorization policy is in effect, this will return a sequence with the single value pyramid.security.Everyone (the special principal identifier representing all principals).

652

57.3. CONSTANTS

latex-note.png

even if an authorization policy is in effect, some (exotic) authorization policies may not implement the required machinery for this function; those will cause a NotImplementedError exception to be raised when this function is invoked.

view_execution_permitted(context, request, name=’‘)

If the view specified by context and name is protected by a permission, check the permission associated with the view using the effective authentication/authorization policies and the request. Return a boolean result. If no authorization policy is in effect, or if the view is not protected by a permission, return True.

57.3 Constants

Everyone

The special principal id named ‘Everyone’. This principal id is granted to all requests. Its actual value is the string ‘system.Everyone’.

Authenticated

The special principal id named ‘Authenticated’. This principal id is granted to all requests which contain any other non-Everyone principal id (according to the authentication policy). Its actual value is the string ‘system.Authenticated’.

ALL_PERMISSIONS

An object that can be used as the permission member of an ACE which matches all permissions unconditionally. For example, an ACE that uses ALL_PERMISSIONS might be composed like so:

(’Deny’, ’system.Everyone’, ALL_PERMISSIONS).

DENY_ALL

A convenience shorthand ACE that defines (’Deny’, ’system.Everyone’, ALL_PERMISSIONS). This is often used as the last ACE in an ACL in systems that use an “inheriting” security policy, representing the concept “don’t inherit any other ACEs”.

NO_PERMISSION_REQUIRED

A special permission which indicates that the view should always be executable by entirely anonymous users, regardless of the default permission, bypassing any authorization policy that may be in effect. Its actual value is the string ‘__no_permission_required__’.

653

57. PYRAMID.SECURITY

57.4 Return Values

Allow

The ACE “action” (the first element in an ACE e.g. (Allow, Everyone, ’read’) that means allow access. A sequence of ACEs makes up an ACL. It is a string, and its actual value is “Allow”.

Deny

The ACE “action” (the first element in an ACE e.g. (Deny, ’george’, ’read’) that means deny access. A sequence of ACEs makes up an ACL. It is a string, and its actual value is “Deny”.

class ACLDenied

An instance of ACLDenied represents that a security check made explicitly against ACL was denied. It evaluates equal to all boolean false types. It also has the following attributes: acl, ace, permission, principals, and context. These attributes indicate the security values involved in the request. Its __str__ method prints a summary of these attributes for debugging purposes. The same summary is available as the msg attribute.

class ACLAllowed

An instance of ACLAllowed represents that a security check made explicitly against ACL was allowed. It evaluates equal to all boolean true types. It also has the following attributes: acl, ace, permission, principals, and context. These attributes indicate the security values involved in the request. Its __str__ method prints a summary of these attributes for debugging purposes. The same summary is available as the msg attribute.

class Denied

An instance of Denied is returned when a security-related API or other Pyramid code denies an action unrelated to an ACL check. It evaluates equal to all boolean false types. It has an attribute named msg describing the circumstances for the deny.

class Allowed

An instance of Allowed is returned when a security-related API or other Pyramid code allows an action unrelated to an ACL check. It evaluates equal to all boolean true types. It has an attribute named msg describing the circumstances for the allow.

654

CHAPTER

FIFTYEIGHT

PYRAMID.SETTINGS

get_settings()

Return a deployment settings object for the current application. The object is a dictionary-like object that contains key/value pairs based on the dictionary passed as the settings argument to the pyramid.config.Configurator constructor or the pyramid.router.make_app()

API.

asbool(s)

Return the boolean value True if the case-lowered value of string input s is any of t, true, y, on, or 1, otherwise return the boolean value False. If s is the value None, return False. If s is already one of the boolean values True or False, return it.

aslist(value, flatten=True)

Return a list of strings, separating the input based on newlines and, if flatten=True (the default), also split on spaces within each line.

655