pyams_utils package¶
Subpackages¶
- pyams_utils.interfaces package
- Submodules
- pyams_utils.interfaces.data module
- pyams_utils.interfaces.intids module
- pyams_utils.interfaces.site module
- pyams_utils.interfaces.size module
- pyams_utils.interfaces.tales module
- pyams_utils.interfaces.text module
- pyams_utils.interfaces.timezone module
- pyams_utils.interfaces.traversing module
- pyams_utils.interfaces.tree module
- pyams_utils.interfaces.zeo module
- Module contents
- pyams_utils.protocol package
- pyams_utils.scripts package
- pyams_utils.tests package
- pyams_utils.timezone package
- pyams_utils.widget package
- pyams_utils.zmi 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 < ò > entity.<br /></p></div>''' >>> html_to_text(html) 'Header\nThis is an < ò > entity.\n\n'
>>> html = '''<div><p>Header</p><p>This is an < ò > 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.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 thestr()
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…' >>> get_text_start('This is a long string', 20) 'This is a long…' >>> 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
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