--- 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] + '…'
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)