lazy_text Module

Strings, reStructuredText, docstrings and other general text processing

Summary of module contents:

Name Description
multiplication_formatter Formats a value * symbol ** power as a string.
pair_strings_sum_formatter Formats the sum of a and b.
float_str This is a StrategyDict instance object called float_str. Strategies stored: 3.
rst_table Creates a reStructuredText simple table (list of strings) from a list of lists.
small_doc Finds a useful small doc representation of an object.
format_docstring Parametrized decorator for adding/changing a function docstring.
multiplication_formatter(power, value, symbol)[source]

Formats a value * symbol ** power as a string.

Usually symbol is already a string and both other inputs are numbers, however this isn’t strictly needed. If symbol is a number, the multiplication won’t be done, keeping its default string formatting as is.

pair_strings_sum_formatter(a, b)[source]

Formats the sum of a and b.

Note

Both inputs are numbers already converted to strings.

rst_table(data, schema=None)[source]

Creates a reStructuredText simple table (list of strings) from a list of lists.

small_doc(obj, indent='', max_width=80)[source]

Finds a useful small doc representation of an object.

Parameters:
  • obj – Any object, which the documentation representation should be taken from.
  • indent – Result indentation string to be insert in front of all lines.
  • max_width – Each line of the result may have at most this length.
Returns:

For classes, modules, functions, methods, properties and StrategyDict instances, returns the first paragraph in the doctring of the given object, as a list of strings, stripped at right and with indent at left. For other inputs, it will use themselves cast to string as their docstring.

format_docstring(template_='{__doc__}', *args, **kwargs)[source]

Parametrized decorator for adding/changing a function docstring.

For changing a already available docstring in the function, the "{__doc__}" in the template is replaced by the original function docstring.

Parameters:
  • template – A format-style template.
  • [*args

    ...

  • **kwargs]

    Positional and keyword arguments passed to the formatter.

Examples:

Closure docstring personalization:

>>> def add(n):
...   @format_docstring(number=n)
...   def func(m):
...     '''Adds {number} to the given value.'''
...     return n + m
...   return func
>>> add(3).__doc__
'Adds 3 to the given value.'
>>> add("__").__doc__
'Adds __ to the given value.'

Same but using a lambda (you can also try with **locals()):

>>> def add_with_lambda(n):
...   return format_docstring("Adds {0}.", n)(lambda m: n + m)
>>> add_with_lambda(15).__doc__
'Adds 15.'
>>> add_with_lambda("something").__doc__
'Adds something.'

Mixing both template styles with {__doc__}:

>>> templ = "{0}, {1} is my {name} docstring:{__doc__}->\nEND!"
>>> @format_docstring(templ, "zero", "one", "two", name="testing", k=[1, 2])
... def test():
...   '''
...   Not empty!
...   {2} != {k[0]} but {2} == {k[1]}
...   '''
>>> print(test.__doc__)
zero, one is my testing docstring:
  Not empty!
  two != 1 but two == 2
  ->
END!

lazy_text.float_str StrategyDict

This is a StrategyDict instance object called float_str. Strategies stored: 3.

Strategy float_str.auto (Default). Docstring starts with:

Pretty string from int/float.

Strategy float_str.frac. Aliases available are float_str.fraction, float_str.ratio, float_str.rational. Docstring starts with:

Pretty rational string from float numbers.

Strategy float_str.pi. Docstring starts with:

String formatter for fractions of \(\pi\).

Note

This docstring is self-generated, see the StrategyDict class and the strategies docs for more details.

auto(value, order='pprpr', size=[4, 5, 3, 6, 4], after=False, max_denominator=1000000)

Pretty string from int/float.

“Almost” automatic string formatter for integer fractions, fractions of \(\pi\) and float numbers with small number of digits.

Outputs a representation among float_str.pi, float_str.frac (without a symbol) strategies, as well as the usual float representation. The formatter is chosen by counting the resulting length, trying each one in the given order until one gets at most the given size limit parameter as its length.

Parameters:
  • value – A float number or an iterable with floats.
  • order – A string that gives the order to try formatting. Each char should be: - "p" for pi formatter (float_str.pi); - "r" for ratio without symbol (float_str.frac); - "f" for the float usual base 10 decimal representation. Defaults to "pprpr". If no trial has the desired size, returns the float representation.
  • size – The max size allowed for each formatting in the order, respectively. Defaults to [4, 5, 3, 6, 4].
  • after – Chooses the place where the \(\pi\) symbol should appear, when such formatter apply. If True, that’s the end of the string. If False, that’s in between the numerator and the denominator, before the slash. Defaults to False.
  • max_denominator – The data in value is rounded following the limit given by this parameter when trying to represent it as a fraction/ratio. Defaults to the integer 1,000,000 (one million).
Returns:

A string with the number written into.

Note

You probably want to keep max_denominator high to avoid rounding.

pi(value, after=False, max_denominator=1000000)

String formatter for fractions of \(\pi\).

Alike the rational_formatter, but fixed to the symbol string float_str.pi_symbol and value float_str.pi_value (both can be changed, if needed), mainly intended for direct use with MatPlotLib labels.

Examples:
>>> float_str.pi_symbol = "pi" # Just for printing sake
>>> float_str.pi(pi / 2)
'pi/2'
>>> float_str.pi(pi * .333333333333333)
'pi/3'
>>> float_str.pi(pi * .222222222222222)
'2pi/9'
>>> float_str.pi_symbol = " PI" # With the space
>>> float_str.pi(pi / 2, after=True)
'1/2 PI'
>>> float_str.pi(pi * .333333333333333, after=True)
'1/3 PI'
>>> float_str.pi(pi * .222222222222222, after=True)
'2/9 PI'

See also

float_str.frac
Float to string conversion, perhaps with a symbol as a multiplier.
frac(value, symbol_str='', symbol_value=1, after=False, max_denominator=1000000)

Pretty rational string from float numbers.

Converts a given numeric value to a string based on rational fractions of the given symbol, useful for labels in plots.

Parameters:
  • value – A float number or an iterable with floats.
  • symbol_str – String data that will be in the output representing the data as a numerator multiplier, if needed. Defaults to an empty string.
  • symbol_value – The conversion value for the given symbol (e.g. pi = 3.1415...). Defaults to one (no effect).
  • after – Chooses the place where the symbol_str should be written. If True, that’s the end of the string. If False, that’s in between the numerator and the denominator, before the slash. Defaults to False.
  • max_denominator – An int instance, used to round the float following the given limit. Defaults to the integer 1,000,000 (one million).
Returns:

A string with the rational number written into as a fraction, with or without a multiplying symbol.

Examples:
>>> float_str.frac(12.5)
'25/2'
>>> float_str.frac(0.333333333333333)
'1/3'
>>> float_str.frac(0.333)
'333/1000'
>>> float_str.frac(0.333, max_denominator=100)
'1/3'
>>> float_str.frac(0.125, symbol_str="steps")
'steps/8'
>>> float_str.frac(0.125, symbol_str=" Hz",
...                after=True) # The symbol includes whitespace!
'1/8 Hz'

See also

float_str.pi
This fraction/ratio formatter, but configured with the “pi” symbol.