- -
-

PyAMS utilities

- -
-

Module contents

-
-
-pyams_utils.includeme(config)
-

pyams_utils features include

-
- -
-
-

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

Bases: object

-

An adapter which always return None!

-

Can be useful to override a default 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.dict module

-
-
-pyams_utils.dict.update_dict(input, key, value)
-

Update given mapping if input value is a boolean ‘true’ value

- --- - - - -
Parameters:
    -
  • input (dict) – input dictionary
    • -
  • key – mapping key
    • -
  • value – new value
    • -
-
-

‘False’ values leave mapping unchanged:

-
>>> from pyams_utils.dict import update_dict
->>> mydict = {}
->>> update_dict(mydict, 'key1', None)
->>> mydict
-
-
-

{} ->>> update_dict(mydict, ‘key1’, ‘’) ->>> mydict -{} ->>> update_dict(mydict, ‘key1’, 0) ->>> mydict -{}

-

‘True’ values modify the mapping:

-
>>> update_dict(mydict, 'key1', 'value')
->>> mydict
-
-
-

{‘key1’: ‘value’} ->>> update_dict(mydict, ‘key1’, ‘value2’) ->>> mydict -{‘key1’: ‘value2’}

-
- -
-
-

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.fanstatic module

-
-
-class pyams_utils.fanstatic.ExternalResource(library, path, defer=False, **kwargs)
-

Bases: fanstatic.core.Resource

-

Fanstatic external resource

-
-
-render(library_url)
-
- -
- -
-
-class pyams_utils.fanstatic.FanstaticTalesExtension(context, request, view)
-

Bases: pyams_utils.adapter.ContextRequestViewAdapter

-

extension:resource_path() TALES extension

-

This TALES extension generates an URL matching a given Fanstatic resource. -Resource is given as a string made of package name (in dotted form) followed by a colon and by the resource name.

-

For example:

-
.. code-block:: html
-
-
-
-
<div tal:attributes=”data-ams-plugin-pyams_content-src extension:resource_path(‘pyams_content.skin:pyams_content’)” />
-
-
-render(resource)
-
- -
- -
-
-pyams_utils.fanstatic.get_resource_path(resource, signature='--static--', versioning=True)
-

Get path for given resource

-
- -
-
-pyams_utils.fanstatic.render_js(url, defer=False)
-
- -
-
-

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

Get current or global registry

-
- -
-
-pyams_utils.registry.get_global_registry()
-

Get global registry

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

-
-
-class pyams_utils.request.PyAMSRequest(environ, charset=None, unicode_errors=None, decode_param_names=None, **kw)
-

Bases: pyramid.request.Request

-

Custom request factory

-

Used to add ‘context’ argument to ‘effective_principals’ method call -to be able to get ‘roles’ principals

-
-
-has_permission(x, *args, **kwargs)
-
- -
- -
-
-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.request_property(key=None, prefix=None)
-

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

-

If no 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) – annotations 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.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

-
- -
-
-exception pyams_utils.schema.InvalidEmail
-

Bases: zope.schema._bootstrapinterfaces.ValidationError

-

Email address must be entered as « name@domain.name », without ‘<’ and ‘>’ characters

-
- -
-
-class pyams_utils.schema.MailAddressField(*args, **kw)
-

Bases: zope.schema._bootstrapfields.TextLine

-

Mail address 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.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.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 7f1fadbcfa20>
-
- -
- -
-
-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, query=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
    • -
  • query (str/dict) – an optional URL arguments string or mapping
    • -
-
-

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 this class is required only for tasks specifically targeting a ZEO database connection (like a ZEO -packer scheduler task); for generic ZODB operations, just use a ZODBConnection class defined through -Pyramid’s configuration file.

-

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
-

BLOBs directory: 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
-

Connection name: Registration name of ZEO connection

-
- -
-
-password
-

ZEO password: User password on ZEO server

-
- -
-
-server_name
-

ZEO server name: Hostname of ZEO server

-
- -
-
-server_port
-

ZEO server port: Port number of ZEO server

-
- -
-
-server_realm
-

ZEO server realm: Realm name on ZEO server

-
- -
-
-shared_blob_dir
-

Shared BLOBs directory ?: Flag whether the blob_dir is a server-shared filesystem that should be used instead of transferring blob data over zrpc.

-
- -
-
-storage
-

ZEO server 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
-

ZEO user name: 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

-
- -
-
-class pyams_utils.zodb.ZODBConnection(name='', settings=None)
-

Bases: object

-

ZODB connection wrapper

-

Connections are extracted from Pyramid’s settings file in zodbconn.uri entries.

-

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

-
from pyams_utils.zodb import ZODBConnection
-
-def my_method(zodb_name):
-    zodb_connection = ZODBConnection(zodb_name)
-    with zodb_connection as root:
-        # *root* is then the ZODB root object
-        # do whatever you want with ZODB connection,
-        # which is closed automatically
-
-
-
-
-close()
-
- -
-
-connection
-
- -
-
-db
-
- -
-
-get_connection()
-

Load named connection matching registry settings

-
- -
-
-storage
-
- -
- -
-
-class pyams_utils.zodb.ZODBConnectionVocabulary(context=None)
-

Bases: zope.schema.vocabulary.SimpleVocabulary

-

ZODB connections vocabulary

-
- -
-
-pyams_utils.zodb.get_connection_from_settings(settings=None)
-

Load connection matching registry settings

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

-
- -
-
-pyams_utils.zodb.object_key_adapter(obj)
-
- -
-
-pyams_utils.zodb.persistent_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.persistent_transaction_manager(obj)
-
- -
-
-
- - -