+ +
+

pyams_utils package

+ +
+

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

+
+ +
+
+ + +