pyams/pyams_utils: comparison src/pyams

equal deleted inserted replaced

-:2022e4da3ad9
+:63284c98cdc1
 # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
 # 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
 import docutils.core
 from markdown import markdown
 from pyramid.interfaces import IRequest
 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
 from pyams_utils.request import check_request
 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)
 'This is a&#133;'
 >>> get_text_start('This is a long string', 20)
 return result
 index = length - 1
 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
 Truncates a sentence if it is longer than the specified 'length' characters.
 Truncated strings will end with an ellipsis character (“…”)
 See also 'get_text_start'
 """
 @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)
 class BaseHTMLRenderer(ContextRequestAdapter):
 """Raw text HTML renderer
 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
 @adapter_config(name='text', context=(str, IRequest), provides=IHTMLRenderer)
 class TextRenderer(BaseHTMLRenderer):
 def text_to_html(text, renderer='text'):
 """Convert text to HTML using the given renderer
 Renderer name can be any registered HTML renderer adapter.
-You can provide several renderers by giving their names separated by semicolon; renderers will then
+You can provide several renderers by giving their names separated by semicolon; renderers
-act as in a pipe, each renderer transforming output of the previous one.
+will then act as in a pipe, each renderer transforming output of the previous one.
 """
 request = check_request()
 registry = request.registry
 for renderer_name in renderer.split(';'):
 renderer = registry.queryMultiAdapter((text, request), IHTMLRenderer, name=renderer_name)
 if renderer is not None:
 text = renderer.render() or text
 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`
+If first *context* argument of the renderer is an object for which an
-adapter can be found, this adapter is used to render the context to HTML; if *context* is a string,
+:py:class:`IHTMLRenderer <pyams_utils.interfaces.text.IHTMLRenderer>`
-it is converted to HTML using the renderer defined as second parameter; otherwise, context is just
+adapter can be found, this adapter is used to render the context to HTML; if *context* is a
-converted to string using the :py:func:`str` function.
+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 ''
 registry = self.request.registry
 adapter = registry.queryMultiAdapter((context, self.request, self.view), IHTMLRenderer)
 if adapter is None:
 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'
 @vocabulary_config(name=PYAMS_HTML_RENDERERS_VOCABULARY)
 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
 terms = []
 append = terms.append
 breaks with given CSS class.
 """
 @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)

branch	dev-tf
changeset 427	63284c98cdc1
parent 321	247c4f2948ef
child 445	98b00191ce4f