xdoctest.utils.util_str module

Utilities related to string manipulations

xdoctest.utils.util_str.strip_ansi(text)

Removes all ansi directives from the string.

Parameters:

text (str)

Returns:

str

References

http://stackoverflow.com/questions/14693701/remove-ansi https://stackoverflow.com/questions/13506033/filtering-out-ansi-escape-sequences

Examples

>>> line = '\t\u001b[0;35mBlabla\u001b[0m     \u001b[0;36m172.18.0.2\u001b[0m'
>>> escaped_line = strip_ansi(line)
>>> assert escaped_line == '\tBlabla     172.18.0.2'

xdoctest.utils.util_str.color_text(text, color)

Colorizes text a single color using ansii tags.

Parameters:

• text (str) – text to colorize

• color (str) – may be one of the following: yellow, blink, lightgray, underline, darkyellow, blue, darkblue, faint, fuchsia, black, white, red, brown, turquoise, bold, darkred, darkgreen, reset, standout, darkteal, darkgray, overline, purple, green, teal, fuscia

Returns:

colorized text.

If pygments is not installed plain text is returned.

Return type:

str

Example

>>> import sys
>>> if sys.platform.startswith('win32'):
>>>     import pytest
>>>     pytest.skip()
>>> text = 'raw text'
>>> from xdoctest import utils
>>> from xdoctest.utils import util_str
>>> if utils.modname_to_modpath('pygments') and not util_str.NO_COLOR:
>>>     # Colors text only if pygments is installed
>>>     import pygments
>>>     print('pygments = {!r}'.format(pygments))
>>>     ansi_text1 = color_text(text, 'red')
>>>     print('ansi_text1 = {!r}'.format(ansi_text1))
>>>     ansi_text = utils.ensure_unicode(ansi_text1)
>>>     prefix = utils.ensure_unicode('\x1b[31')
>>>     print('prefix = {!r}'.format(prefix))
>>>     print('ansi_text = {!r}'.format(ansi_text))
>>>     assert ansi_text.startswith(prefix)
>>>     assert color_text(text, None) == 'raw text'
>>> else:
>>>     # Otherwise text passes through unchanged
>>>     assert color_text(text, 'red') == 'raw text'
>>>     assert color_text(text, None) == 'raw text'

xdoctest.utils.util_str.ensure_unicode(text)

Casts bytes into utf8 (mostly for python2 compatibility)

Parameters:

text (str)

Returns:

str

References

http://stackoverflow.com/questions/12561063/python-extract-data-from-file

CommandLine

python -m xdoctest.utils ensure_unicode

Example

>>> assert ensure_unicode('my ünicôdé strįng') == 'my ünicôdé strįng'
>>> assert ensure_unicode('text1') == 'text1'
>>> assert ensure_unicode('text1'.encode('utf8')) == 'text1'
>>> assert ensure_unicode('text1'.encode('utf8')) == 'text1'
>>> import codecs
>>> assert (codecs.BOM_UTF8 + 'text»¿'.encode('utf8')).decode('utf8')

xdoctest.utils.util_str.indent(text, prefix='    ')

Indents a block of text

Parameters:

• text (str) – text to indent

• prefix (str) – prefix to add to each line (default = ‘ ‘)

Returns:

indented text

Return type:

str

CommandLine

python -m xdoctest.utils ensure_unicode

Example

>>> text = 'Lorem ipsum\ndolor sit amet'
>>> prefix = '    '
>>> result = indent(text, prefix)
>>> assert all(t.startswith(prefix) for t in result.split('\n'))

xdoctest.utils.util_str.highlight_code(text, lexer_name='python', **kwargs)

Highlights a block of text using ansi tags based on language syntax.

Parameters:

• text (str) – plain text to highlight

• lexer_name (str) – name of language

• **kwargs – passed to pygments.lexers.get_lexer_by_name

Returns:

texthighlighted text

If pygments is not installed, the plain text is returned.

Return type:

str

CommandLine

python -c "import pygments.formatters; print(list(pygments.formatters.get_all_formatters()))"

Example

>>> text = 'import xdoctest as xdoc; print(xdoc)'
>>> new_text = highlight_code(text)
>>> print(new_text)

xdoctest.utils.util_str.add_line_numbers(source, start=1, n_digits=None)

Prefixes code with line numbers

Parameters:

• source (str | List[str])

• start (int)

• n_digits (int | None)

Returns:

List[str] | str

Example

>>> print(chr(10).join(add_line_numbers(['a', 'b', 'c'])))
1 a
2 b
3 c
>>> print(add_line_numbers(chr(10).join(['a', 'b', 'c'])))
1 a
2 b
3 c

xdoctest.utils.util_str.codeblock(block_str)

Wraps multiline string blocks and returns unindented code. Useful for templated code defined in indented parts of code.

Parameters:

block_str (str) – typically in the form of a multiline string

Returns:

the unindented string

Return type:

str

Example

>>> # Simulate an indented part of code
>>> if True:
...     # notice the indentation on this will be normal
...     codeblock_version = codeblock(
...             '''
...             def foo():
...                 return 'bar'
...             '''
...         )
...     # notice the indentation and newlines on this will be odd
...     normal_version = ('''
...         def foo():
...             return 'bar'
...     ''')
>>> assert normal_version != codeblock_version
>>> print('Without codeblock')
>>> print(normal_version)
>>> print('With codeblock')
>>> print(codeblock_version)