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.1.0-py3.5.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:

.. code-block:: python

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:

.. code-block:: html
<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:

.. code-block:: html
<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:

.. code-block:: html
<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(*, convert_charrefs=True)

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

HTML parser should handle entities correctly:

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

>>> 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 < ò > 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.

class pyams_utils.property.classproperty(fget=None, fset=None, fdel=None, doc=None)

Bases: object

Same decorator as property(), but passes obj.__class__ instead of obj to fget/fset/fdel.

Original code for property emulation: https://docs.python.org/3.5/howto/descriptor.html#properties

deleter(fdel)
getter(fget)
setter(fset)
pyams_utils.property.classproperty_support(cls)

Class decorator to add metaclass to a class.

Metaclass uses to add descriptors to class attributes

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.1.0-py3.5.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 to call a custom named adapter providing ITALESExtension interface.

transform = <Symbol value=<function render_extension> at 7f0a5e278ef0>
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 adapter 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