diff -r 2022e4da3ad9 -r 63284c98cdc1 src/pyams_utils/text.py
--- a/src/pyams_utils/text.py	Sat Nov 23 01:24:11 2019 +0100
+++ b/src/pyams_utils/text.py	Sat Nov 23 14:57:24 2019 +0100
@@ -10,7 +10,11 @@
 # FOR A PARTICULAR PURPOSE.
 #
 
-__docformat__ = 'restructuredtext'
+"""PyAMS_utils.text module
+
+This module provides text manipulation and conversion functions, as well as a set of TALES
+extensions (see :py:class:`ITALESExtension <pyams_utils.interfaces.tales.ITALESExtension>`).
+"""
 
 import html
 
@@ -20,7 +24,6 @@
 from zope.interface import Interface
 from zope.schema.vocabulary import SimpleTerm, SimpleVocabulary
 
-from pyams_utils import _
 from pyams_utils.adapter import ContextRequestAdapter, ContextRequestViewAdapter, adapter_config
 from pyams_utils.interfaces.tales import ITALESExtension
 from pyams_utils.interfaces.text import IHTMLRenderer
@@ -28,14 +31,20 @@
 from pyams_utils.vocabulary import vocabulary_config
 
 
-def get_text_start(text, length, max=0):
+__docformat__ = 'restructuredtext'
+
+
+from pyams_utils import _
+
+
+def get_text_start(text, length, maxlen=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
 
     :param str text: initial text
     :param integer length: maximum length of resulting text
-    :param integer max: if > 0, *text* is shortened only if remaining text is longer than max
+    :param integer maxlen: 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)
@@ -52,12 +61,13 @@
     text_length = len(result)
     while (index > 0) and (result[index] != ' '):
         index -= 1
-    if (index > 0) and (text_length > index + max):
+    if (index > 0) and (text_length > index + maxlen):
         return result[:index] + '&#133;'
     return text
 
 
-@adapter_config(name='truncate', context=(Interface, Interface, Interface), provides=ITALESExtension)
+@adapter_config(name='truncate', context=(Interface, Interface, Interface),
+                provides=ITALESExtension)
 class TruncateCharsTalesExtension(ContextRequestViewAdapter):
     """extension:truncate(value, length, max) TALES expression
 
@@ -67,10 +77,13 @@
     """
 
     @staticmethod
-    def render(value, length=50, max=0):
+    def render(value, length=50, maxlen=0):
+        """Render TALES extension;
+        see :py:class:`ITALESExtension <pyams_utils.interfaces.tales.ITALESExtension>`
+        """
         if not value:
             return ''
-        return get_text_start(value, length, max=max)
+        return get_text_start(value, length, maxlen=maxlen)
 
 
 @adapter_config(name='raw', context=(str, IRequest), provides=IHTMLRenderer)
@@ -80,7 +93,8 @@
     This renderer renders input text 'as is', mainly for use in a <pre> tag.
     """
 
-    def render(self, **kwargs):
+    def render(self, **kwargs):  # pylint: disable=unused-argument
+        """Convert raw code as HTML"""
         return self.context
 
 
@@ -152,8 +166,8 @@
 
     Renderer name can be any registered HTML renderer adapter.
 
-    You can provide several renderers by giving their names separated by semicolon; renderers will then
-    act as in a pipe, each renderer transforming output of the previous one.
+    You can provide several renderers by giving their names separated by semicolon; renderers
+    will then act as in a pipe, each renderer transforming output of the previous one.
     """
     request = check_request()
     registry = request.registry
@@ -164,24 +178,28 @@
     return text
 
 
-empty_marker = object()
+EMPTY_MARKER = object()
 
 
 @adapter_config(name='html', context=(Interface, Interface, Interface), provides=ITALESExtension)
 class HTMLTalesExtension(ContextRequestViewAdapter):
     """*extension:html* TALES expression
 
-    If first *context* argument of the renderer is an object for which an :py:class:`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 :py:func:`str` function.
+    If first *context* argument of the renderer is an object for which an
+    :py:class:`IHTMLRenderer <pyams_utils.interfaces.text.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 :py:func:`str` function.
 
-    You can provide several renderers by giving their names separated by semicolon; renderers will then
-    act as in a pipe, each renderer transforming output of the previous one.
+    You can provide several renderers by giving their names separated by semicolon; renderers
+    will then act as in a pipe, each renderer transforming output of the previous one.
     """
 
-    def render(self, context=empty_marker, renderer='text'):
-        if context is empty_marker:
+    def render(self, context=EMPTY_MARKER, renderer='text'):
+        """Render TALES extension;
+        see :py:class:`ITALESExtension <pyams_utils.interfaces.tales.ITALESExtension>`
+        """
+        if context is EMPTY_MARKER:
             context = self.context
         if not context:
             return ''
@@ -191,10 +209,9 @@
             adapter = registry.queryMultiAdapter((context, self.request), IHTMLRenderer)
         if adapter is not None:
             return adapter.render()
-        elif isinstance(context, str):
+        if isinstance(context, str):
             return text_to_html(context, renderer)
-        else:
-            return str(context)
+        return str(context)
 
 
 PYAMS_HTML_RENDERERS_VOCABULARY = 'PyAMS HTML renderers'
@@ -204,7 +221,7 @@
 class RenderersVocabulary(SimpleVocabulary):
     """Text renderers vocabulary"""
 
-    def __init__(self, context=None):
+    def __init__(self, context=None):  # pylint: disable=unused-argument
         request = check_request()
         registry = request.registry
         translate = request.localizer.translate
@@ -226,12 +243,15 @@
 
     @staticmethod
     def render(value, css_class='', character='|', start_tag=None, end_tag=None):
+        """Render TALES extension;
+        see :py:class:`ITALESExtension <pyams_utils.interfaces.tales.ITALESExtension>`
+        """
         if not value:
             return ''
-        br = '<br {0} />'.format('class="{0}"'.format(css_class) if css_class else '')
+        br_tag = '<br {0} />'.format('class="{0}"'.format(css_class) if css_class else '')
         elements = value.split(character)
         if start_tag:
             elements[0] = '<{0}>{1}</{0}>'.format(start_tag, elements[0])
         if end_tag:
             elements[-1] = '<{0}>{1}</{0}>'.format(end_tag, elements[-1])
-        return br.join(elements)
+        return br_tag.join(elements)