- -

-

pyams_utils package¶

-

Subpackages¶

-

Submodules¶

-

pyams_utils.adapter module¶

-

Adapters management package

-

This package provides a small set of standard base adapters for context, context and request, and -context and request and view.

-

See Managing ZCA with PyAMS to see how PyAMS can help components management.

-

-class pyams_utils.adapter.ContextAdapter(context)¶

Bases: object

-

Context adapter

-

- -

-class pyams_utils.adapter.ContextRequestAdapter(context, request)¶

Bases: object

-

Context + request multi-adapter

-

- -

-class pyams_utils.adapter.ContextRequestViewAdapter(context, request, view)¶

Bases: object

-

Context + request + view multi-adapter

-

- -

-class pyams_utils.adapter.adapter_config(**settings)¶

Bases: object

-

Function or class decorator to declare an adapter

-

Annotation parameters can be:

- --- - - - -

Parameters:	- name (str) – (default=’‘), name of the adapter - context ([Interface...]) – an interface, or a tuple of interfaces, that the component adapts - provides (Interface) – the interface that the adapter provides - -

-

-venusian = <module 'venusian' from '/var/local/env/pyams/eggs/venusian-1.0-py3.4.egg/venusian/__init__.py'>¶

- -

-

pyams_utils.attr module¶

-

-class pyams_utils.attr.AttributeTraverser(context)¶

Bases: pyams_utils.adapter.ContextAdapter

-

++attr++ namespace traverser

-

This custom traversing adapter can be used to access an object attribute directly from -an URL by using a path like this:

-

/path/to/object/++attr++name
-

-

-

Whare name is the name of the requested attribute

-

-traverse(name, furtherpath=None)¶

- -

-

pyams_utils.container module¶

-

-class pyams_utils.container.BTreeOrderedContainer¶

Bases: zope.container.ordered.OrderedContainer

-

BTree based ordered container

-

This container maintain a manual order of it’s contents

-

- -

-class pyams_utils.container.ContainerSublocationsAdapter(context)¶

Bases: pyams_utils.adapter.ContextAdapter

-

Contained object sub-locations adapter

-

This adapter checks for custom ISublocations interface adapters which can -be defined by any component to get access to inner locations, defined for -example via annotations.

-

-sublocations()¶: See zope.location.interfaces.ISublocations interface
-

- -

-pyams_utils.container.find_objects_matching(root, condition, ignore_root=False)¶

Find all objects in root that match the condition

-

The condition is a Python callable object that takes an object as -argument and must return a boolean result.

-

All sub-objects of the root will also be searched recursively.

- --- - - - - - -

Parameters:	- root (object) – the parent object from which search is started - condition (callable) – a callable object which may return true for a given -object to be selected - ignore_root (boolean) – if True, the root object will not be returned, even if it matches -the given condition - -
Returns:	an iterator for all root’s sub-objects matching condition -

-

- -

-pyams_utils.container.find_objects_providing(root, interface)¶

Find all objects in root that provide the specified interface

-

All sub-objects of the root will also be searched recursively.

- --- - - - - - -

Parameters:	- root (object) – object; the parent object from which search is started - interface (Interface) – interface; an interface that sub-objects should provide - -
Returns:	an iterator for all root’s sub-objects that provide the given interface -

-

- -

-

pyams_utils.context module¶

-

-class pyams_utils.context.ContextSelector(ifaces, config)¶

Bases: object

-

Interface based context selector

-

This selector can be used as a subscriber predicate to define -an interface that the context must support for the event to be applied:

-

from pyams_utils.interfaces.site import ISiteRoot
-
-@subscriber(IObjectModifiedEvent, context_selector=ISiteRoot)
-def siteroot_modified_event_handler(event):
-    '''This is an event handler for an ISiteRoot object modification event'''
-

-

-

-phash()¶

- -

-text()¶

- -

-

pyams_utils.data module¶

-

Object data API module

-

The IObjectData interface is a generic interface which can be used to assign custom data to nay object. -This object data may be any object which can be serialized to JSON, and assigned to any HTML data attribute. -It can typically be used to set a data-ams-data attribute to objects, which is afterwards converted to -classic data- attributes by MyAMS.js framework.

-

For example, for a custom widget in a form:

-

def updateWidgets(self):
-    super(MyForm, self).updateWidgets()
-    widget = self.widgets['mywidget']
-    alsoProvides(widget, IObjectData)
-    widget.object_data = {'ams-colorpicker-position': 'top left'}
-

-

-

You can then set an attribute in a TAL template like this:

-

<div tal:attributes="data-ams-data extension:object_data(widget)">...</div>
-

-

-

After data initialization by MyAMS.js, the following code will be converted to:

-

<div data-ams-colorpicker-position="top left">...</div>
-

-

-

-class pyams_utils.data.BrowserRequestDataExtension(context, request, view)¶

Bases: pyams_utils.adapter.ContextRequestViewAdapter

-

extension:request_data TALES extension for Zope browser request

-

This TALES extension can be used to get a request data, previously stored in the request via an annotation. -For example:

-

<div tal:content="extension:request_data('my.annotation.key')">...</div>
-

-

-

-render(params=None)¶: See pyams_utils.interfaces.tales.ITALESExtension interface
-

- -

-class pyams_utils.data.ObjectDataExtension(context, request, view)¶

Bases: pyams_utils.adapter.ContextRequestViewAdapter

-

extension:object_data TALES extension

-

This TALES extension is to be used in Chameleon templates to define a custom data attribute -which stores all object data (see pyams_utils.interfaces.data.IObjectData interface), like this:

-

<div tal:attributes="data-ams-data extension:object_data(context)">...</div>
-

-

-

-render(context=None)¶: See pyams_utils.interfaces.tales.ITALESExtension interface
-

- -

-class pyams_utils.data.ObjectDataRenderer(context)¶

Bases: pyams_utils.adapter.ContextAdapter

-

Object data JSON renderer

-

-get_object_data()¶: See pyams_utils.interfaces.data.IObjectDataRenderer interface
-

- -

-class pyams_utils.data.PyramidRequestDataExtension(context, request, view)¶

Bases: pyams_utils.adapter.ContextRequestViewAdapter

-

extension:request_data TALES extension for Pyramid request

-

This TALES extension can be used to get a request data, previously stored in the request via an annotation. -For example:

-

<div tal:content="extension:request_data('my.annotation.key')">...</div>
-

-

-

-render(params=None)¶: See pyams_utils.interfaces.tales.ITALESExtension interface
-

- -

-

pyams_utils.date module¶

-

-pyams_utils.date.date_to_datetime(value)¶

Get datetime value converted from a date or datetime object

- --- - - - - - -

Parameters:	value (date/datetime) – a date or datetime value to convert
Returns:	datetime; input value converted to datetime

-

>>> from datetime import date, datetime
->>> from pyams_utils.date import date_to_datetime
->>> value = date(2016, 11, 15)
->>> date_to_datetime(value)
-datetime.datetime(2016, 11, 15, 0, 0)
->>> value = datetime(2016, 11, 15, 10, 13, 12)
->>> value
-datetime.datetime(2016, 11, 15, 10, 13, 12)
->>> date_to_datetime(value) is value
-True
-

-

-

- -

-pyams_utils.date.format_date(value, format='on %d/%m/%Y', request=None)¶

Format given date with the given format

- --- - - - - - -

Parameters:	- value (datetime) – the value to format - format (str) – a format string to use by strftime function - request – the request from which to extract localization info for translation - -
Returns:	str; input datetime converted to given format -

-

>>> from datetime import datetime
->>> from pyams_utils.date import format_date, SH_DATE_FORMAT
->>> value = datetime(2016, 11, 15, 10, 13, 12)
->>> format_date(value)
-'on 15/11/2016'
->>> format_date(value, SH_DATE_FORMAT)
-'15/11/2016'
-

-

-

- -

-pyams_utils.date.format_datetime(value, format='on %d/%m/%Y at %H:%M', request=None)¶

Format given datetime with the given format including time

- --- - - - - - -

Parameters:	- value (datetime) – the value to format - format (str) – a format string to use by strftime function - request – request; the request from which to extract localization info for translation - -
Returns:	str; input datetime converted to given format -

-

>>> from datetime import datetime
->>> from pyams_utils.date import format_datetime, SH_DATETIME_FORMAT
->>> value = datetime(2016, 11, 15, 10, 13, 12)
->>> format_datetime(value)
-'on 15/11/2016 at 10:13'
->>> format_datetime(value, SH_DATETIME_FORMAT)
-'15/11/2016 - 10:13'
-

-

-

- -

-pyams_utils.date.get_age(value, request=None)¶

Get ‘human’ age of a given datetime (including timezone) compared to current datetime (in UTC)

- --- - - - - - -

Parameters:	value (datetime) – input datetime to be compared with current datetime
Returns:	str; the delta value, converted to months, weeks, days, hours or minutes

-

- -

-pyams_utils.date.get_duration(v1, v2=None, request=None)¶

Get ‘human’ delta as string between two dates

- --- - - - - - -

Parameters:	- v1 (datetime) – start date - v2 (datetime) – end date, or current date (in UTC) if None - request – the request from which to extract localization infos - -
Returns:	str; approximate delta between the two input dates -

-

>>> from datetime import datetime
->>> from pyams_utils.date import get_duration
->>> from pyramid.testing import DummyRequest
->>> request = DummyRequest()
->>> date1 = datetime(2015, 1, 1)
->>> date2 = datetime(2014, 3, 1)
->>> get_duration(date1, date2, request)
-'10 months'
-

-

-

Dates order is not important:

-

>>> get_duration(date2, date1, request)
-'10 months'
->>> date2 = datetime(2014, 11, 10)
->>> get_duration(date1, date2, request)
-'7 weeks'
->>> date2 = datetime(2014, 12, 26)
->>> get_duration(date1, date2, request)
-'6 days'
-

-

-

For durations lower than 2 days, duration also display hours:

-

>>> date1 = datetime(2015, 1, 1)
->>> date2 = datetime(2015, 1, 2, 15, 10, 0)
->>> get_duration(date1, date2, request)
-'1 day and 15 hours'
->>> date2 = datetime(2015, 1, 2)
->>> get_duration(date1, date2, request)
-'24 hours'
->>> date2 = datetime(2015, 1, 1, 13, 12)
->>> get_duration(date1, date2, request)
-'13 hours'
->>> date2 = datetime(2015, 1, 1, 1, 15)
->>> get_duration(date1, date2, request)
-'75 minutes'
->>> date2 = datetime(2015, 1, 1, 0, 0, 15)
->>> get_duration(date1, date2, request)
-'15 seconds'
-

-

-

- -

-pyams_utils.date.parse_date(value)¶

Get date specified in unicode ISO format to Python datetime object

-

Dates are always assumed to be stored in GMT timezone

- --- - - - - - -

Parameters:	value (str) – unicode date to be parsed
Returns:	datetime; the specified value, converted to datetime

-

>>> from pyams_utils.date import parse_date
->>> parse_date('2016-11-15T10:13:12+00:00')
-datetime.datetime(2016, 11, 15, 10, 13, 12, tzinfo=<StaticTzInfo 'GMT'>)
-

-

-

- -

-pyams_utils.date.unidate(value)¶

Get specified date converted to unicode ISO format

-

Dates are always assumed to be stored in GMT timezone

- --- - - - - - -

Parameters:	value (date) – input date to convert to unicode
Returns:	unicode; input date converted to unicode

-

>>> from datetime import datetime
->>> from pyams_utils.date import unidate
->>> value = datetime(2016, 11, 15, 10, 13, 12)
->>> unidate(value)
-'2016-11-15T10:13:12+00:00'
-

-

-

- -

-

pyams_utils.decorator module¶

-

-pyams_utils.decorator.deprecated(*msg)¶: This is a decorator which can be used to mark functions -as deprecated. It will result in a warning being emitted -when the function is used.
-

- -

-

pyams_utils.encoding module¶

-

-class pyams_utils.encoding.EncodingField(vocabulary='PyAMS encodings', **kw)¶

Bases: zope.schema._field.Choice

-

Encoding schema field

-

- -

-class pyams_utils.encoding.EncodingsVocabulary(terms, *interfaces)¶

Bases: zope.schema.vocabulary.SimpleVocabulary

-

A vocabulary containing a set of registered encodings

-

- -

-

pyams_utils.html module¶

-

-class pyams_utils.html.MyHTMLParser(strict=<object object>, *, convert_charrefs=<object object>)¶

Bases: html.parser.HTMLParser

-

HTML parser

-

-charrefs = {34: '"', 38: '&', 39: "'", 60: '<', 62: '>', 192: 'À', 193: 'A', 194: 'Â', 195: 'A', 196: 'Ä', 197: 'A', 198: 'AE', 199: 'Ç', 200: 'È', 201: 'É', 202: 'Ê', 203: 'Ë', 204: 'I', 205: 'I', 206: 'Î', 207: 'Ï', 208: 'D', 209: 'N', 210: 'O', 211: 'O', 212: 'Ô', 213: 'O', 214: 'Ö', 215: 'x', 216: 'O', 217: 'Ù', 218: 'U', 219: 'Û', 220: 'Ü', 221: 'Y', 222: 'T', 223: 'sz', 224: 'à', 225: 'a', 226: 'â', 227: 'a', 228: 'ä', 229: 'a', 230: 'ae', 231: 'ç', 232: 'è', 233: 'é', 234: 'ê', 235: 'ë', 236: 'i', 237: 'i', 238: 'î', 239: 'ï', 240: 'e', 241: 'n', 242: 'o', 243: 'o', 244: 'ô', 245: 'o', 246: 'ö', 248: 'o', 249: 'ù', 250: 'u', 251: 'û', 252: 'ü', 253: 'y', 255: 'ÿ'}¶

- -

-data = ''¶

- -

-entitydefs = {'ecirc': 'ê', 'aring': 'a', 'Aring': 'A', 'thorn': 't', 'agrave': 'à', 'Ograve': 'O', 'ocirc': 'ô', 'Eacute': 'È', 'eacute': 'é', 'atilde': 'a', 'iuml': 'ï', 'aelig': 'ae', 'igrave': 'i', 'Auml': 'Ä', 'Uuml': 'Ü', 'ucirc': 'û', 'ugrave': 'ù', 'iacute': 'i', 'ograve': 'o', 'oacute': 'o', 'Euml': 'Ë', 'apos': "'", 'Ouml': 'Ö', 'aacute': 'a', 'Ccedil': 'Ç', 'Oslash': 'O', 'egrave': 'è', 'Uacute': 'U', 'uacute': 'u', 'Igrave': 'I', 'Agrave': 'À', 'Iuml': 'I', 'Otilde': 'O', 'Yacute': 'Y', 'ntilde': 'n', 'Ugrave': 'Ù', 'Ucirc': 'Û', 'icirc': 'î', 'Ecirc': 'Ê', 'Ntilde': 'N', 'Egrave': 'É', 'nbsp': ' ', 'quot': '"', 'oslash': 'o', 'ouml': 'ö', 'yacute': 'y', 'uuml': 'ü', 'yuml': 'ÿ', 'Aacute': 'A', 'Icirc': 'I', 'euml': 'ë', 'otilde': 'o', 'auml': 'ä', 'ccedil': 'ç', 'Oacute': 'O', 'lt': '<', 'amp': '&', 'Iacute': 'I', 'Ocirc': 'Ô', 'gt': '>', 'Atilde': 'A', 'acirc': 'â', 'Acirc': 'Â', 'THORN': 'T', 'AElig': 'AE'}¶

- -

-handle_charref(name)¶

- -

-handle_data(data)¶

- -

-handle_endtag(tag)¶

- -

-handle_entityref(name)¶

- -

-handle_starttag(tag, attrs)¶

- -

-pyams_utils.html.html_to_text(value)¶

Utility function to extract text content from HTML

-

>>> from pyams_utils.html import html_to_text
->>> html = '''<p>This is a HTML text part.</p>'''
->>> html_to_text(html)
-'This is a HTML text part.\n'
-

-

-

HTML parser should handle entities correctly:

-

>>> html = '''<div><p>Header</p><p>This is an &lt;&nbsp;&#242;&nbsp;&gt; entity.<br /></p></div>'''
->>> html_to_text(html)
-'Header\nThis is an < o > entity.\n\n'
-

-

-

- -

-

pyams_utils.i18n module¶

-

-pyams_utils.i18n.get_browser_language(request)¶

Custom locale negotiator

-

Copied from zope.publisher code

-

- -

-pyams_utils.i18n.normalize_lang(lang)¶

- -

-

pyams_utils.include module¶

-

-pyams_utils.include.include_package(config)¶: Pyramid package include
-

- -

-

pyams_utils.intids module¶

-

-class pyams_utils.intids.UniqueIdAdapter(context)¶

Bases: pyams_utils.adapter.ContextAdapter

-

Object unique ID adapter

-

This adapter is based on a registered IIntIds utility to get a unique ID -for any persistent object.

-

-oid¶: Get context ID in hexadecimal form
-

- -

-pyams_utils.intids.handle_added_object(event)¶

Notify IntId utility for added objects

-

This subscriber is used for all persistent objects to be registered -in all locally registered IIntIds utilities.

-

- -

-pyams_utils.intids.handle_intid_event(event)¶: Event subscriber used to dispatch all IIntIdEvent events using Pyramid events subscribers to matching -subscribers using Zope events
-

- -

-pyams_utils.intids.handle_removed_object(event)¶

Notify IntId utility for removed objects

-

This subscriber is used for all persistent objects to be unregistered -from all locally registered IIntIds utilities.

-

- -

-

pyams_utils.list module¶

-

-pyams_utils.list.unique(seq, idfun=None)¶

Extract unique values from list, preserving order

- --- - - - - - -

Parameters:	- seq (list) – input list - idfun (callable) – an identity function which is used to get ‘identity’ value of each element -in the list - -
Returns:	list; a new list containing only unique elements of the original list in their initial order. -Original list is not modified. -

-

>>> from pyams_utils.list import unique
->>> mylist = [1, 2, 3, 2, 1]
->>> unique(mylist)
-[1, 2, 3]
-

-

-

>>> mylist = [3, 2, 2, 1, 4, 2]
->>> unique(mylist)
-[3, 2, 1, 4]
-

-

-

You can also set an ‘id’ function applied on each element:

-

>>> mylist = [1, 2, 3, '2', 4]
->>> unique(mylist, idfun=str)
-[1, 2, 3, 4]
-

-

-

- -

-

pyams_utils.lock module¶

-

-class pyams_utils.lock.CacheLock(name, wait=True)¶

Bases: object

-

Beaker based lock

-

This lock can be used when you need to get a lot across several processes or even computers. -The lock relies on a shared value stored into a shared Beaker cache.

- --- - - - -

Parameters:	- name (str) – name of the lock to use as shared key - wait (boolean) – if False, a LockException is raised if lock can’t be taken; otherwise, -application waits until lock is released - -

-

Lock can be used as a context manager.

-

- -

-exception pyams_utils.lock.LockException¶

Bases: Exception

-

Cache lock exception

-

- -

-pyams_utils.lock.get_locks_cache()¶: Get locks shared cache
-

- -

-pyams_utils.lock.locked(name, wait=True)¶

Locked function decorator

-

Can be used with any function or method which requires a global shared lock.

- --- - - - -

Parameters:	- name (str) – name of the lock to use as shared key - wait (boolean) – if False, a LockException is raised if lock can’t be taken; otherwise, -application waits until lock is released - -

-

- -

-

pyams_utils.progress module¶

-

-pyams_utils.progress.get_progress_cache()¶: Get cache storing tasks progress
-

- -

-pyams_utils.progress.get_progress_status_view(request)¶

Get progress status of a given task

-

Each submitted task is identified by an ID defined when the task is created

-

- -

-pyams_utils.progress.get_running_tasks()¶: Get list of running tasks
-

- -

-pyams_utils.progress.get_tasks_cache()¶: Get cache storing tasks list
-

- -

-pyams_utils.progress.set_running_tasks(tasks)¶: Update list of running tasks
-

- -

-

pyams_utils.property module¶

-

-class pyams_utils.property.DocFieldProperty(field, name=None)¶: Bases: zope.schema.fieldproperty.FieldProperty
-

- -

-class pyams_utils.property.cached(function)¶

Bases: object

-

Custom property decorator to define a property or function which is calculated only once

-

When applied on a function, caching is based on input arguments

-

-expire(*args)¶

- -

-class pyams_utils.property.cached_property(fget, doc=None)¶

Bases: object

-

A read-only property decorator that is only evaluated once.

-

The value is cached on the object itself rather than the function or class; this should prevent -memory leakage.

-

- -

-pyams_utils.property.request_property(key, prefix=None)¶

Define a method decorator used to store result into current request’s annotations

-

If not request is currently running, a new one is created. -key is a required argument; if None, the key will be the method’s object

- --- - - - -

Parameters:	- key (str) – session’s value key; if None, the key will be the method’s object; if key is a callable -object, it will be called to get the actual session key - prefix – str; prefix to use for session key; if None, the prefix will be the property name - -

-

- -

-pyams_utils.property.session_property(app, key=None, prefix=None)¶

Define a method decorator used to store result into request’s session

-

If no request is currently running, a new one is created.

- --- - - - -

Parameters:	- app (str) – application identifier used to prefix session keys - key (str) – session’s value key; if None, the key will be the method’s object; if key is a callable -object, il will be called to get the actual session key - prefix – str; prefix to use for session key; if None, the prefix will be the property name - -

-

- -

-

pyams_utils.registry module¶

-

Local registry management package

-

This package is used to manage local registry. A local registry is a site management component -created automatically on application startup by PyAMS_utils package. It can be used to store and register -components, mainly utilities which are created and configured dynamically by a site administrator; this can include -SQLAlchemy engines, ZEO connections, and several PyAMS utilities like security manager, medias converter, -tasks scheduler and many other ones.

-

See Managing ZCA with PyAMS to get a brief introduction about using a local registry with PyAMS packages.

-

-class pyams_utils.registry.LocalRegistry¶

Bases: _thread._local

-

Local registry

-

-get_registry()¶

- -

-set_registry(registry)¶

- -

-pyams_utils.registry.get_all_utilities_registered_for(interface)¶

Get list of registered utilities for given interface

-

Do a registry lookup for matching utilities into local registry first, then on each registry -associated with current thread stack.

-

- -

-pyams_utils.registry.get_local_registry()¶: Get local registry
-

- -

-pyams_utils.registry.get_registries()¶

Iterator on components registries

-

Returns an iterator on current local registry (if any) and registries associated -in current thread stack.

-

- -

-pyams_utils.registry.get_utilities_for(interface)¶

Get utilities registered with given interface as (name, util) tuples iterator

-

Do a registry lookup for matching utilities into local registry first, then on each registry -associated with current thread stack.

-

- -

-pyams_utils.registry.get_utility(provided, name='')¶

Get utility registered with given interface

-

Do a registry lookup for given utility into local registry first, then on each registry -associated with current thread stack.

- --- - - - - - -

Parameters:	- provided (Interface) – the requested interface - name (str) – name of the requested utility - -
Returns:	object; the requested object. A ComponentLookupError is raised if the utility -can’t be found. -

-

- -

-pyams_utils.registry.handle_new_request(event)¶

New request event subscriber

-

Is used to initialize local registry to None for any new request

-

- -

-pyams_utils.registry.handle_site_before_traverse(event)¶

Before traverse event subscriber

-

Define site’s local registry when an object implementing ISite is traversed

-

- -

-pyams_utils.registry.query_utility(provided, name='', default=None)¶

Query utility registered with given interface

-

Do a registry lookup for given utility into local registry first, then on each registry -associated with current thread stack.

- --- - - - - - -

Parameters:	- provided (Interface) – the requested interface - name (str) – name of the requested utility - default (object) – the default object returned if the requested utility can’t be found - -
Returns:	object; the requested object, or default if it can’t be found -

-

- -

-pyams_utils.registry.registered_utilities()¶

Get utilities registrations as generator

-

Iterates over utilities defined in all registries, starting with local ones.

-

- -

-pyams_utils.registry.set_local_registry(registry)¶: Define local registry
-

- -

-class pyams_utils.registry.utility_config(**settings)¶

Bases: object

-

Function or class decorator to register a utility in the global registry

- --- - - - -

Parameters:	- name (str) – default=’‘; name under which the utility is registered - provides (Interface) – the interface for which the utility is registered - -

-

Please note that a single utility can be registered several times (using several annotations).

-

-venusian = <module 'venusian' from '/var/local/env/pyams/eggs/venusian-1.0-py3.4.egg/venusian/__init__.py'>¶

- -

-

pyams_utils.request module¶

-

-pyams_utils.request.check_request(path='/', environ=None, base_url=None, headers=None, POST=None, **kw)¶: Get current request, or create a new blank one if missing
-

- -

-pyams_utils.request.get_annotations(request)¶

Define ‘annotations’ request property

-

This function is automatically defined as a custom request method on package include.

-

- -

-pyams_utils.request.get_debug(request)¶

Define ‘debug’ request property

-

This function is automatically defined as a custom request method on package include.

-

- -

-pyams_utils.request.get_request(raise_exception=True)¶

Get current request

-

Raises a NoInteraction exception if there is no active request.

-

- -

-pyams_utils.request.get_request_data(request, key, default=None)¶

Get data associated with request

- --- - - - - - -

Parameters:	- request – the request containing requested data - key (str) – request data annotation key - default (object) – the default value when data is missing - -
Returns:	the requested value, or default -

-

- -

-pyams_utils.request.query_request()¶

Query current request

-

Returns None if there is no active request

-

- -

-pyams_utils.request.set_request_data(request, key, value)¶

Associate data with request

- --- - - - -

Parameters:	- request – the request in which to set data - key (str) – request data annotation key - value (object) – the value to be set in request annotation - -

-

- -

-

pyams_utils.schema module¶

-

-class pyams_utils.schema.ColorField(*args, **kw)¶

Bases: zope.schema._bootstrapfields.TextLine

-

Color field

-

- -

-class pyams_utils.schema.DatesRangeField(value_type=None, unique=False, **kw)¶

Bases: zope.schema._field.Tuple

-

Dates range field

-

- -

-class pyams_utils.schema.DottedDecimalField(*args, **kw)¶

Bases: zope.schema._field.Decimal

-

Dotted decimal field

-

- -

-class pyams_utils.schema.EncodedPassword(*args, **kw)¶

Bases: zope.schema._bootstrapfields.Password

-

Encoded password field

-

-constraint(value)¶

- -

-fromUnicode(str)¶

- -

-class pyams_utils.schema.HTMLField(*args, **kw)¶

Bases: zope.schema._bootstrapfields.Text

-

HTML field

-

- -

-class pyams_utils.schema.PersistentDict(key_type=None, value_type=None, **kw)¶

Bases: zope.schema._field.Dict

-

Persistent mapping field

-

- -

-class pyams_utils.schema.PersistentList(value_type=None, unique=False, **kw)¶

Bases: zope.schema._field.List

-

Persistent list field

-

- -

-class pyams_utils.schema.TextLineListField(value_type=None, unique=False, **kw)¶

Bases: zope.schema._field.List

-

TextLine list field

-

- -

-

pyams_utils.session module¶

-

-pyams_utils.session.get_session_data(request, app, key, default=None)¶

Get data associated with current user session

-

PyAMS session management is based on Beaker package session management.

- --- - - - -

Parameters:	- request – the request from which session is extracted - app (str) – application name - key (str) – session data key for given application - default – object; requested session data, or default if it can’t be found - -

-

APPLICATION_KEY = 'MyApp'
-SESSION_KEY = 'MyFunction'
-
-def my_function(request):
-    return get_session_data(request, APPLICATION_KEY, SESSION_KEY)
-

-

-

- -

-pyams_utils.session.set_session_data(request, app, key, value)¶

Associate data with current user session

- --- - - - -

Parameters:	- request – the request from which session is extracted - app (str) – application name - key (str) – session data key for given application - value (object) – any object that can be pickled can be stored into user session - -

-

APPLICATION_KEY = 'MyApp'
-SESSION_KEY = 'MyFunction'
-
-def my_function(request):
-    value = {'key1': 'value1', 'key2': 'value2'}
-    set_session_data(request, APPLICATION_KEY, SESSION_KEY, value)
-

-

-

- -

-

pyams_utils.site module¶

-

-class pyams_utils.site.BaseSiteRoot¶

Bases: zope.container.folder.Folder, zope.site.site.SiteManagerContainer

-

Default site root

-

A site root can be used as base application root in your ZODB. -It’s also site root responsibility to manage your local site manager.

-

BaseSiteRoot defines a basic ACL which gives all permissions to system administrator.

-

-config_klass = None¶

- -

-class pyams_utils.site.NewLocalSiteCreatedEvent(object)¶

Bases: zope.interface.interfaces.ObjectEvent

-

New local site creation event

-

- -

-class pyams_utils.site.SiteRootEtcTraverser(context)¶

Bases: pyams_utils.adapter.ContextAdapter

-

Site root ++etc++ namespace traverser

-

Gives access to local site manager from /++etc++site URL

-

-traverse(name, furtherpath=None)¶

- -

-class pyams_utils.site.SiteUpgradeEvent(object)¶

Bases: zope.interface.interfaces.ObjectEvent

-

Site upgrade request event

-

- -

-pyams_utils.site.check_required_utilities(site, utilities)¶

Utility function to check for required utilities

- --- - - - -

Parameters:	- site (object) – the site manager into which configuration may be checked - utilities (tuple) – each element of the tuple is another tuple made of the utility interface, -the utility registration name, the utility factory and the object name when creating the utility, as in: - -

-

REQUIRED_UTILITIES = ((ISecurityManager, '', SecurityManager, 'Security manager'),
-                      (IPrincipalAnnotationUtility, '', PrincipalAnnotationUtility, 'User profiles'))
-

-

-

- -

-pyams_utils.site.site_factory(request)¶

Application site factory

-

On application startup, this factory checks configuration to get application name and -load it from the ZODB; if the application can’t be found, configuration is scanned to -get application factory, create a new one and create a local site manager.

-

- -

-pyams_utils.site.site_upgrade(request)¶

Upgrade site when needed

-

This function is executed by pyams_upgrade console script. -Site generations are registered named utilities providing -ISiteGenerations interface.

-

Current site generations are stored into annotations for each generation adapter.

-

- -

-

pyams_utils.size module¶

-

-pyams_utils.size.get_human_size(value, request=None)¶

Convert given bytes value in human readable format

-

>>> from pyramid.testing import DummyRequest
->>> request = DummyRequest(params={'_LOCALE_': 'en'})
->>> request.locale_name
-'en'
->>> from pyams_utils.size import get_human_size
->>> get_human_size(256, request)
-'256 bytes'
->>> get_human_size(3678, request)
-'3.6 Kb'
->>> get_human_size(6785342, request)
-'6.47 Mb'
->>> get_human_size(3674815342, request)
-'3.422 Gb'
->>> request = DummyRequest(params={'_LOCALE_': 'fr'})
->>> request.locale_name
-'fr'
->>> get_human_size(256, request)
-'256 bytes'
->>> get_human_size(3678, request)
-'3,6 Kb'
->>> get_human_size(6785342, request)
-'6,47 Mb'
->>> get_human_size(3674815342, request)
-'3,422 Gb'
-

-

-

- -

-

pyams_utils.tales module¶

-

-class pyams_utils.tales.ContextExprMixin¶

Bases: object

-

Mixin-class for expression compilers

-

-transform = None¶

- -

-class pyams_utils.tales.ExtensionExpr(expression, braces_required=False)¶

Bases: pyams_utils.tales.ContextExprMixin, chameleon.tales.StringExpr

-

extension: TALES expression

-

This expression can be used a call a custom named adapter providing ITALESExtension interface.

-

-transform = <Symbol value=<function render_extension> at 7f3cb9015518>¶

- -

-pyams_utils.tales.render_extension(econtext, name)¶

TALES extension renderer

-

See Custom TALES extensions for complete description.

-

- -

-

pyams_utils.text module¶

-

-class pyams_utils.text.BaseHTMLRenderer(context, request)¶

Bases: object

-

Raw text HTML renderer

-

This renderer renders input text ‘as is’, mainly for use in a <pre> tag.

-

-render(**kwargs)¶

- -

-class pyams_utils.text.HTMLTalesExtension(context, request, view)¶

Bases: pyams_utils.adapter.ContextRequestViewAdapter

-

extension:html TALES expression

-

If first context argument of the renderer is an object for which an IHTMLRenderer -can be found, this adapter is used to render the context to HTML; if context is a string, -it is converted to HTML using the renderer defined as second parameter; otherwise, context is just -converted to string using the str() function.

-

-render(context=None, renderer='text')¶

- -

-class pyams_utils.text.ReStructuredTextRenderer(context, request)¶

Bases: pyams_utils.text.BaseHTMLRenderer

-

reStructuredText HTML renderer

-

This renderer is using docutils to render HTML output.

-

-render(**kwargs)¶: Render reStructuredText to HTML
-

- -

-class pyams_utils.text.RenderersVocabulary¶

Bases: zope.schema.vocabulary.SimpleVocabulary

-

Text renderers vocabulary

-

- -

-class pyams_utils.text.TextRenderer(context, request)¶

Bases: pyams_utils.text.BaseHTMLRenderer

-

Basic text HTML renderer

-

This renderer only replace newlines with HTML breaks.

-

-render(**kwargs)¶

- -

-pyams_utils.text.get_text_start(text, length, max=0)¶

Get first words of given text with maximum given length

-

If max is specified, text is shortened only if remaining text is longer this value

- --- - - - -

Parameters:	- text (str) – initial text - length (integer) – maximum length of resulting text - max (integer) – if > 0, text is shortened only if remaining text is longer than max - -

-

>>> from pyams_utils.text import get_text_start
->>> get_text_start('This is a long string', 10)
-'This is a&#133;'
->>> get_text_start('This is a long string', 20)
-'This is a long&#133;'
->>> get_text_start('This is a long string', 20, 7)
-'This is a long string'
-

-

-

- -

-pyams_utils.text.text_to_html(text, renderer='text')¶

Convert text to HTML using the given renderer

-

Renderer name can be any registered HTML renderer adapter

-

- -

-

pyams_utils.traversing module¶

-

-class pyams_utils.traversing.NamespaceTraverser(root)¶

Bases: pyramid.traversal.ResourceTreeTraverser

-

Custom traverser handling views and namespaces

-

This is an upgraded version of native Pyramid traverser. -It adds: -- a new BeforeTraverseEvent before traversing each object in the path -- support for namespaces with “++” notation

-

-NAMESPACE_SELECTOR = '++'¶

- -

-class pyams_utils.traversing.PathElementsAdapter(context)¶

Bases: pyams_utils.adapter.ContextAdapter

-

Contained object path elements adapter

-

This interface is intended to be used inside a keyword index to -be able to search object based on a given parent

-

-parents¶

- -

-pyams_utils.traversing.get_parent(context, interface=<InterfaceClass zope.interface.Interface>, allow_context=True, condition=None)¶

Get first parent of the context that implements given interface

- --- - - - -

Parameters:

context (object) – base element
interface (Interface) – the interface that parend should implement
allow_context (boolean) – if ‘True’ (the default), traversing is done starting with context; otherwise, -traversing is done starting from context’s parent
condition (callable) – an optional function that should return a ‘True’ result when called with parent -as first argument

-

- -

-

pyams_utils.unicode module¶

-

-pyams_utils.unicode.decode(value, encoding='utf-8')¶

Decode given bytes value to unicode with given encoding

- --- - - - - - -

Parameters:	- value (bytes) – the value to decode - encoding (str) – selected encoding - -
Returns:	str; value decoded to unicode string if input is a bytes, original value otherwise -

-

>>> from pyams_utils.unicode import decode
->>> decode(b'Cha\xc3\xaene accentu\xc3\xa9e')
-'Chaîne accentuée'
->>> decode(b'Cha\xeene accentu\xe9e', 'latin1')
-'Chaîne accentuée'
-

-

-

- -

-pyams_utils.unicode.encode(value, encoding='utf-8')¶

Encode given Unicode value to bytes with given encoding

- --- - - - - - -

Parameters:	- value (str) – the value to encode - encoding (str) – selected encoding - -
Returns:	bytes; value encoded to bytes if input is a string, original value otherwise -

-

>>> from pyams_utils.unicode import encode
->>> encode('Chaîne accentuée')
-b'Cha\xc3\xaene accentu\xc3\xa9e'
->>> encode('Chaîne accentuée', 'latin1')
-b'Cha\xeene accentu\xe9e'
-

-

-

- -

-pyams_utils.unicode.nvl(value, default='')¶

Get specified value, or an empty string if value is empty

- --- - - - - - -

Parameters:	- value (object) – value to be checked - default (object) – default value to be returned if value is false - -
Returns:	input value, or default if value is false -

-

>>> from pyams_utils.unicode import nvl
->>> nvl(None)
-''
->>> nvl('foo')
-'foo'
->>> nvl(False, 'bar')
-'bar'
-

-

-

- -

-pyams_utils.unicode.translate_string(s, escape_slashes=False, force_lower=True, spaces=' ', remove_punctuation=True, keep_chars='_-.')¶

Remove extended characters and diacritics from string and replace them with ‘basic’ ones

- --- - - - - - -

Parameters:

s (str) – text to be cleaned.
escape_slashes (boolean) – if True, slashes are also converted
force_lower (boolean) – if True, result is automatically converted to lower case
spaces (str) – character used to replace spaces
remove_punctuation (boolean) – if True, all punctuation characters are removed
keep_chars (str) – characters which may be kept in the input string

-

Returns:

text without diacritics or special characters

-

>>> from pyams_utils.unicode import translate_string
->>> input = 'Ceci est un test en Français !!!'
->>> translate_string(input)
-'ceci est un test en francais'
->>> translate_string(input, force_lower=False)
-'Ceci est un test en Francais'
->>> translate_string(input, spaces='-')
-'ceci-est-un-test-en-francais'
->>> translate_string(input, remove_punctuation=False)
-'ceci est un test en francais !!!'
->>> translate_string(input, keep_chars='!')
-'ceci est un test en francais !!!'
-

-

-

- -

-pyams_utils.unicode.unidict(value, encoding='utf-8')¶

Get specified dict with values converted to unicode

- --- - - - - - -

Parameters:	value (dict) – input mapping of strings which may be converted to unicode
Returns:	dict; a new mapping with each value converted to unicode

-

>>> from pyams_utils.unicode import unidict
->>> unidict({'input': b'Cha\xc3\xaene accentu\xc3\xa9e'})
-{'input': 'Chaîne accentuée'}
->>> unidict({'input': b'Cha\xeene accentu\xe9e'}, 'latin1')
-{'input': 'Chaîne accentuée'}
-

-

-

- -

-pyams_utils.unicode.unilist(value, encoding='utf-8')¶

Get specified list with values converted to unicode

- --- - - - - - -

Parameters:	value (list) – input list of strings which may be converted to unicode
Returns:	list; a new list with each value converted to unicode

-

>>> from pyams_utils.unicode import unilist
->>> unilist([b'Cha\xc3\xaene accentu\xc3\xa9e'])
-['Chaîne accentuée']
->>> unilist([b'Cha\xeene accentu\xe9e'], 'latin1')
-['Chaîne accentuée']
-

-

-

- -

-pyams_utils.unicode.uninvl(value, default='', encoding='utf-8')¶

Get specified value converted to unicode, or an empty unicode string if value is empty

- --- - - - - - -

Parameters:	- value (str/bytes) – the input to be checked - default – str; default value - encoding – str; encoding name to use for conversion - -
Returns:	str; value, or default if value is empty, converted to unicode -

-

>>> from pyams_utils.unicode import uninvl
->>> uninvl('String value')
-'String value'
->>> uninvl(b'String value')
-'String value'
->>> uninvl(b'Cha\xc3\xaene accentu\xc3\xa9e')
-'Chaîne accentuée'
->>> uninvl(b'Cha\xeene accentu\xe9e', 'latin1')
-'Chaîne accentuée'
-

-

-

- -

-pyams_utils.unicode.utf8(value)¶

Encode given unicode value to UTF-8 encoded bytes

- --- - - - - - -

Parameters:	value (str) – the value to encode to utf-8
Returns:	bytes; value encoded to bytes if input is a string, original value otherwise

-

>>> from pyams_utils.unicode import utf8
->>> utf8('Chaîne accentuée')
-b'Cha\xc3\xaene accentu\xc3\xa9e'
-

-

-

- -

-

pyams_utils.url module¶

-

-class pyams_utils.url.AbsoluteUrlTalesExtension(context, request, view)¶

Bases: pyams_utils.adapter.ContextRequestViewAdapter

-

extension:absolute_url(context, view_name) TALES extension

-

A PyAMS TALES extension used to get access to an object URL from a page template.

-

-render(context=None, view_name=None)¶

- -

-pyams_utils.url.absolute_url(context, request, view_name=None)¶

Get resource absolute_url

- --- - - - -

Parameters:	- context (object) – the persistent object for which absolute URL is required - request – the request on which URL is based - view_name (str) – an optional view name to add to URL - -

-

This absolute URL function is based on default Pyramid’s resource_url() function, but -add checks to remove some double slashes, and add control on view name when it begins with a ‘#’ -character which is used by MyAMS.js framework.

-

- -

-

pyams_utils.vocabulary module¶

-

-class pyams_utils.vocabulary.vocabulary_config(name)¶

Bases: object

-

Class decorator to define a vocabulary

- --- - - - -

Parameters:	name (str) – name of the registered vocabulary

-

This is, for example, how a vocabulary of registered ZEO connections utilities is created:

-

from pyams_utils.interfaces.zeo import IZEOConnection
-
-from pyams_utils.registry import get_utilities_for
-from pyams_utils.vocabulary import vocabulary_config
-from zope.schema.vocabulary import SimpleTerm, SimpleVocabulary
-
-@vocabulary_config(name='PyAMS ZEO connections')
-class ZEOConnectionVocabulary(SimpleVocabulary):
-    '''ZEO connections vocabulary'''
-
-    def __init__(self, context=None):
-        terms = [SimpleTerm(name, title=util.name) for name, util in get_utilities_for(IZEOConnection)]
-        super(ZEOConnectionVocabulary, self).__init__(terms)
-

-

-

You can then use such a vocabulary in any schema field:

-

from zope.interface import Interface
-from zope.schema import Choice
-
-class MySchema(Interface):
-    '''Custom schema interface'''
-
-    zeo_connection_name = Choice(title='ZEO connection name',
-                                 description='Please select a registered ZEO connection',
-                                 vocabulary='PyAMS ZEO connections',
-                                 required=False)
-

-

-

- -

-

pyams_utils.wsgi module¶

-

-pyams_utils.wsgi.wsgi_environ_cache(*names)¶

Wrap a function/method to cache its result for call into request.environ

- --- - - - -

Parameters:	names ([string...]) – keys to cache into environ; len(names) must -be equal to the result’s length or scalar

-

- -

-

pyams_utils.zodb module¶

-

-class pyams_utils.zodb.ZEOConnection¶

Bases: object

-

ZEO connection object

-

This object can be used to store all settings to be able to open a ZEO connection.

-

Note that a ZEO connection object is a context manager, so you can use it like this:

-

from pyams_utils.zodb import ZEOConnection
-
-def my_method(zeo_settings):
-    zeo_connection = ZEOConnection()
-    zeo_connection.update(zeo_settings)
-    with zeo_connection as root:
-        # *root* is then the ZODB root object
-        # do whatever you want with ZEO connection,
-        # which is closed automatically
-

-

-

-blob_dir¶: Directory path for blob data
-

- -

-connection¶

- -

-get_connection(wait=False, get_storage=False)¶

Create ZEO client connection from current settings

- --- - - - - - -

Parameters:	- wait (boolean) – should connection wait until storage is ready - get_storage (boolean) – if True, the method should return a tuple containing -storage and DB objects; otherwise only DB object is returned - -
Returns:	tuple containing ZEO client storage and DB object (if get_storage argument is -set to True), or only DB object otherwise -

-

- -

-get_settings()¶

Get mapping of all connection settings

-

These settings can be converted to JSON and sent to another process, for example -via a ØMQ connection.

- --- - - - -

Returns:	dict

-

- -

-name¶: Registration name of ZEO connection
-

- -

-password¶: User password on ZEO server
-

- -

-server_name¶: Hostname of ZEO server
-

- -

-server_port¶: Port number of ZEO server
-

- -

-server_realm¶: Realm name on ZEO server
-

- -

-shared_blob_dir¶: Flag whether the blob_dir is a server-shared filesystem that should be used instead of transferring blob data over zrpc.
-

- -

-storage¶: Storage name on ZEO server
-

- -

-update(settings)¶

Update connection properties with settings as dict

- --- - - - -

Parameters:	settings (dict) – typically extracted via the `get_settings()` method from -another process

-

- -

-username¶: User name on ZEO server
-

- -

-class pyams_utils.zodb.ZEOConnectionUtility¶

Bases: pyams_utils.zodb.ZEOConnection, persistent.Persistent, zope.container.contained.Contained

-

Persistent ZEO connection utility

-

- -

-class pyams_utils.zodb.ZEOConnectionVocabulary(context=None)¶

Bases: zope.schema.vocabulary.SimpleVocabulary

-

ZEO connections vocabulary

-

- -

-pyams_utils.zodb.get_connection(obj)¶

An adapter which gets a ZODB connection from a persistent object

-

We are assuming the object has a parent if it has been created in -this transaction.

-

Raises ValueError if it is impossible to get a connection.

-

- -

-pyams_utils.zodb.get_connection_from_settings(settings)¶: Load connection matching registry settings
-

- -

-pyams_utils.zodb.get_transaction_manager(obj)¶

- -

-pyams_utils.zodb.handle_added_connection(event)¶: Register new ZEO connection when added
-

- -

-pyams_utils.zodb.handle_removed_connection(event)¶: Un-register ZEO connection when deleted
-

- -

-

Module contents¶

-

-pyams_utils.includeme(config)¶: pyams_utils features include
-

- -

-

- - -