# HG changeset patch # User Thierry Florac # Date 1560508866 -7200 # Node ID 2c95d34496f5ad0d9a03d0b85fdfa774de568505 # Parent 6e482f99b30eb80919ee8a8576fb2903717378b5 Docstrings and imports cleanup diff -r 6e482f99b30e -r 2c95d34496f5 src/pyams_utils/__init__.py --- a/src/pyams_utils/__init__.py Wed Jun 12 20:06:45 2019 +0200 +++ b/src/pyams_utils/__init__.py Fri Jun 14 12:41:06 2019 +0200 @@ -10,14 +10,16 @@ # FOR A PARTICULAR PURPOSE. # +"""PyAMS_utils package + +This package provides several small modules dedicated to generic features +for which dedicated packages are not provided. These features can concern +date and times management, strings and unicode, lists and dictionaries, +custom decorators to define several kinds of properties, and so on. +""" + __docformat__ = 'restructuredtext' - -# import standard library - -# import interfaces - -# import packages from zope.schema.fieldproperty import FieldProperty from pyramid.i18n import TranslationStringFactory @@ -25,6 +27,7 @@ def get_field_doc(self): + """Try to get FieldProperty field docstring from field interface""" field = self._FieldProperty__field if field.title and field.description: return '{0}: {1}'.format(field.title, field.description) diff -r 6e482f99b30e -r 2c95d34496f5 src/pyams_utils/data.py --- a/src/pyams_utils/data.py Wed Jun 12 20:06:45 2019 +0200 +++ b/src/pyams_utils/data.py Fri Jun 14 12:41:06 2019 +0200 @@ -10,9 +10,9 @@ # FOR A PARTICULAR PURPOSE. # -__doc__ = """Object data API module +"""Object data API module -The *IObjectData* interface is a generic interface which can be used to assign custom data to nay object. +The *IObjectData* interface is a generic interface which can be used to assign custom data to any 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. @@ -36,19 +36,15 @@ __docformat__ = 'restructuredtext' - -# import standard library import json -# import interfaces +from pyramid.interfaces import IRequest +from zope.interface import Interface +from zope.publisher.interfaces.browser import IBrowserRequest + +from pyams_utils.adapter import ContextAdapter, ContextRequestViewAdapter, adapter_config from pyams_utils.interfaces.data import IObjectData, IObjectDataRenderer from pyams_utils.interfaces.tales import ITALESExtension -from pyramid.interfaces import IRequest -from zope.publisher.interfaces.browser import IBrowserRequest - -# import packages -from pyams_utils.adapter import ContextAdapter, ContextRequestViewAdapter, adapter_config -from zope.interface import Interface @adapter_config(context=IObjectData, provides=IObjectDataRenderer) diff -r 6e482f99b30e -r 2c95d34496f5 src/pyams_utils/i18n.py --- a/src/pyams_utils/i18n.py Wed Jun 12 20:06:45 2019 +0200 +++ b/src/pyams_utils/i18n.py Fri Jun 14 12:41:06 2019 +0200 @@ -10,12 +10,15 @@ # FOR A PARTICULAR PURPOSE. # +"""I18n module used to get browser language from request""" + __docformat__ = 'restructuredtext' import locale def normalize_lang(lang): + """Normalize input languages string""" lang = lang.strip().lower() lang = lang.replace('_', '-') lang = lang.replace(' ', '') @@ -36,17 +39,17 @@ accepts = [] for index, lang in enumerate(accept_langs): - l = lang.split(';', 2) + lang_item = lang.split(';', 2) # If not supplied, quality defaults to 1... quality = 1.0 - if len(l) == 2: - q = l[1] - if q.startswith('q='): - q = q.split('=', 2)[1] + if len(lang_item) == 2: + qual = lang_item[1] + if qual.startswith('q='): + qual = qual.split('=', 2)[1] try: - quality = float(q) + quality = float(qual) except ValueError: # malformed quality value, skip it. continue @@ -58,7 +61,7 @@ # defined, and items with quality defined as 1. quality = 1.9 - (0.001 * index) - accepts.append((quality, l[0])) + accepts.append((quality, lang_item[0])) # Filter langs with q=0, which means # unwanted lang according to the spec @@ -68,7 +71,7 @@ accepts.sort() accepts.reverse() - return [lang for qual, lang in accepts][0] if accepts else None + return [lang for _, lang in accepts][0] if accepts else None def set_locales(config): diff -r 6e482f99b30e -r 2c95d34496f5 src/pyams_utils/inherit.py --- a/src/pyams_utils/inherit.py Wed Jun 12 20:06:45 2019 +0200 +++ b/src/pyams_utils/inherit.py Fri Jun 14 12:41:06 2019 +0200 @@ -10,18 +10,20 @@ # FOR A PARTICULAR PURPOSE. # +"""PyAMS_utils.inherit module + +This module is used to manage a generic inheritance between a content and +it's parent container. It also defines a custom InheritedFieldProperty which +allows to automatically manage inherited properties. +""" + __docformat__ = 'restructuredtext' - -# import standard library - -from zope.interface import implementer, Interface +from zope.interface import Interface, implementer from zope.location import Location from zope.schema.fieldproperty import FieldProperty -# import interfaces from pyams_utils.interfaces.inherit import IInheritInfo -# import packages from pyams_utils.traversing import get_parent from pyams_utils.zodb import volatile_property @@ -37,32 +39,39 @@ @volatile_property def parent(self): + """Get current parent""" return get_parent(self.__parent__, self.target_interface, allow_context=False) @property def can_inherit(self): + """Check if inheritance is possible""" return self.target_interface.providedBy(self.parent) @property def inherit(self): + """Check if inheritance is possible and activated""" return self._inherit if self.can_inherit else False @inherit.setter def inherit(self, value): + """Activate inheritance""" if self.can_inherit: self._inherit = value del self.parent @property def no_inherit(self): + """Inverted boolean value to check if inheritance is possible and activated""" return not bool(self.inherit) @no_inherit.setter def no_inherit(self, value): + """Inverted inheritance setter""" self.inherit = not bool(value) @property def inherit_from(self): + """Get current parent from which we inherit""" if not self.inherit: return self parent = self.parent diff -r 6e482f99b30e -r 2c95d34496f5 src/pyams_utils/interfaces/__init__.py --- a/src/pyams_utils/interfaces/__init__.py Wed Jun 12 20:06:45 2019 +0200 +++ b/src/pyams_utils/interfaces/__init__.py Fri Jun 14 12:41:06 2019 +0200 @@ -10,18 +10,18 @@ # FOR A PARTICULAR PURPOSE. # +"""PyAMS_utils interfaces module + +This module defines several generic constants and interfaces. +It is also used to provide translations to common zope.schema exceptions. +""" + __docformat__ = 'restructuredtext' - -# import standard library - -# import interfaces -from zope.schema.interfaces import WrongContainedType, NotUnique, SchemaNotFullyImplemented, SchemaNotProvided, \ - InvalidURI, InvalidId, InvalidDottedName, Unbound, RequiredMissing, WrongType, TooBig, TooSmall, TooLong, \ - TooShort, InvalidValue, ConstraintNotSatisfied, NotAContainer, NotAnIterator - -# import packages from zope.interface import Interface +from zope.schema.interfaces import ConstraintNotSatisfied, InvalidDottedName, InvalidId, InvalidURI, InvalidValue, \ + NotAContainer, NotAnIterator, NotUnique, RequiredMissing, SchemaNotFullyImplemented, SchemaNotProvided, TooBig, \ + TooLong, TooShort, TooSmall, Unbound, WrongContainedType, WrongType from pyams_utils import _ @@ -56,7 +56,7 @@ # FORBIDDEN_PERMISSION = 'system.forbidden' -'''Custom permission which is never granted to any user''' +'''Custom permission which is never granted to any user, even system manager''' PUBLIC_PERMISSION = 'public' '''Public permission which is granted to every principal''' diff -r 6e482f99b30e -r 2c95d34496f5 src/pyams_utils/interfaces/data.py --- a/src/pyams_utils/interfaces/data.py Wed Jun 12 20:06:45 2019 +0200 +++ b/src/pyams_utils/interfaces/data.py Fri Jun 14 12:41:06 2019 +0200 @@ -10,20 +10,25 @@ # FOR A PARTICULAR PURPOSE. # +"""PyAMS_utils data interface + +This interface allows to define custom "data" properties on any object providing +IObjectData interface. These properties are used to render "data" attributes into +HTML code. +""" + __docformat__ = 'restructuredtext' - -# import standard library - -# import interfaces - -# import packages from zope.interface import Interface from zope.schema import Dict class IObjectData(Interface): - """Object data generic interface""" + """Object data generic interface + + Objects providing this interface can create an 'object_data' dictionary attribute which + will be used to create matching HTML data attributes. + """ object_data = Dict(title="Data associated with this object", required=False) diff -r 6e482f99b30e -r 2c95d34496f5 src/pyams_utils/lock.py --- a/src/pyams_utils/lock.py Wed Jun 12 20:06:45 2019 +0200 +++ b/src/pyams_utils/lock.py Fri Jun 14 12:41:06 2019 +0200 @@ -10,16 +10,17 @@ # FOR A PARTICULAR PURPOSE. # +"""PyAMS_utils.lock module + +This module is use to manage shared locks; these locks can be used accross several +processes; the lock relies on a shared value stored info Beaker's cache. +""" + __docformat__ = 'restructuredtext' - -# import standard library import time from threading import local -# import interfaces - -# import packages from beaker import cache @@ -89,9 +90,11 @@ """ def lock_decorator(func): + def wrapper(*args, **kwargs): with CacheLock(name, wait): return func(*args, **kwargs) + return wrapper return lock_decorator diff -r 6e482f99b30e -r 2c95d34496f5 src/pyams_utils/tests/__init__.py --- a/src/pyams_utils/tests/__init__.py Wed Jun 12 20:06:45 2019 +0200 +++ b/src/pyams_utils/tests/__init__.py Fri Jun 14 12:41:06 2019 +0200 @@ -1,1 +1,31 @@ +# -*- coding: utf-8 -*- ###################################################### +############################################################################## +# +# Copyright (c) 2008-2010 Thierry Florac +# All Rights Reserved. +# +# This software is subject to the provisions of the Zope Public License, +# Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution. +# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED +# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS +# FOR A PARTICULAR PURPOSE. +# +############################################################################## +""" +Generic Test case for ztfy.utils doctest +""" +__docformat__ = 'restructuredtext' + +import os +import sys + + +def get_package_dir(input): + """Get package directory""" + + package_dir = os.path.split(input)[0] + if package_dir not in sys.path: + sys.path.append(package_dir) + return package_dir diff -r 6e482f99b30e -r 2c95d34496f5 src/pyams_utils/tests/test_utilsdocs.py --- a/src/pyams_utils/tests/test_utilsdocs.py Wed Jun 12 20:06:45 2019 +0200 +++ b/src/pyams_utils/tests/test_utilsdocs.py Fri Jun 14 12:41:06 2019 +0200 @@ -1,4 +1,4 @@ -### -*- coding: utf-8 -*- #################################################### +# -*- coding: utf-8 -*- ###################################################### ############################################################################## # # Copyright (c) 2008-2010 Thierry Florac @@ -16,15 +16,18 @@ """ Generic Test case for ztfy.utils doctest """ + __docformat__ = 'restructuredtext' +import doctest +import os import unittest -import doctest -import sys -import os + +from pyams_utils.tests import get_package_dir -current_dir = os.path.dirname(__file__) +CURRENT_DIR = os.path.abspath(os.path.dirname(__file__)) + def doc_suite(test_dir, setUp=None, tearDown=None, globs=None): """Returns a test suite, based on doctests found in /doctest.""" @@ -35,10 +38,7 @@ flags = (doctest.ELLIPSIS | doctest.NORMALIZE_WHITESPACE | doctest.REPORT_ONLY_FIRST_FAILURE) - package_dir = os.path.split(test_dir)[0] - if package_dir not in sys.path: - sys.path.append(package_dir) - + package_dir = get_package_dir(test_dir) doctest_dir = os.path.join(package_dir, 'doctests') # filtering files on extension @@ -53,9 +53,11 @@ return unittest.TestSuite(suite) + def test_suite(): """returns the test suite""" - return doc_suite(current_dir) + return doc_suite(CURRENT_DIR) + if __name__ == '__main__': unittest.main(defaultTest='test_suite') diff -r 6e482f99b30e -r 2c95d34496f5 src/pyams_utils/tests/test_utilsdocstrings.py --- a/src/pyams_utils/tests/test_utilsdocstrings.py Wed Jun 12 20:06:45 2019 +0200 +++ b/src/pyams_utils/tests/test_utilsdocstrings.py Fri Jun 14 12:41:06 2019 +0200 @@ -1,4 +1,4 @@ -### -*- coding: utf-8 -*- #################################################### +# -*- coding: utf-8 -*- ###################################################### ############################################################################## # # Copyright (c) 2008-2010 Thierry Florac @@ -16,15 +16,18 @@ """ Generic Test case for pyams_utils doc strings """ + __docformat__ = 'restructuredtext' +import doctest +import os import unittest -import doctest -import sys -import os + +from pyams_utils.tests import get_package_dir -current_dir = os.path.abspath(os.path.dirname(__file__)) +CURRENT_DIR = os.path.abspath(os.path.dirname(__file__)) + def doc_suite(test_dir, globs=None): """Returns a test suite, based on doc tests strings found in /*.py""" @@ -35,9 +38,7 @@ flags = (doctest.ELLIPSIS | doctest.NORMALIZE_WHITESPACE | doctest.REPORT_ONLY_FIRST_FAILURE) - package_dir = os.path.split(test_dir)[0] - if package_dir not in sys.path: - sys.path.append(package_dir) + package_dir = get_package_dir(test_dir) # filtering files on extension docs = [doc for doc in @@ -57,9 +58,11 @@ return unittest.TestSuite(suite) + def test_suite(): """returns the test suite""" - return doc_suite(current_dir) + return doc_suite(CURRENT_DIR) + if __name__ == '__main__': unittest.main(defaultTest='test_suite') diff -r 6e482f99b30e -r 2c95d34496f5 src/pyams_utils/vocabulary.py --- a/src/pyams_utils/vocabulary.py Wed Jun 12 20:06:45 2019 +0200 +++ b/src/pyams_utils/vocabulary.py Fri Jun 14 12:41:06 2019 +0200 @@ -10,21 +10,22 @@ # FOR A PARTICULAR PURPOSE. # +"""PyAMS_utils.vocabulary module + +This module is used to handle vocabularies. +""" + __docformat__ = 'restructuredtext' - -# import standard library import logging -logger = logging.getLogger('PyAMS (utils)') import venusian - -# import interfaces +from zope.interface import directlyProvides from zope.schema.interfaces import IVocabularyFactory +from zope.schema.vocabulary import getVocabularyRegistry -# import packages -from zope.interface import directlyProvides -from zope.schema.vocabulary import getVocabularyRegistry + +logger = logging.getLogger('PyAMS (utils)') class vocabulary_config: