Module Expr Str Import alias Import alias Import alias FunctionDef arguments args NameParam defaults body Expr Str Assign NameStore Call NameLoad NameLoad If CompareGt Call NameLoad NameLoad Num body Return BinOpAdd BinOpAdd Call AttributeLoad Str attr SubscriptLoad NameLoad Slice Num Str SubscriptLoad NameLoad Index Num orelse If NameLoad body Return SubscriptLoad NameLoad Index Num orelse Return Str decorator_list FunctionDef arguments args NameParam defaults vararg kwarg body Expr Str If NameLoad body AugAssignMod NameStore NameLoad If NameLoad body Assign NameStore Call AttributeLoad NameLoad attr NameLoad Return NameLoad decorator_list FunctionDef arguments args NameParam defaults vararg kwarg body Expr Str Assign NameStore Call AttributeLoad NameLoad attr Assign NameStore Call AttributeLoad Str attr NameLoad Return Call NameLoad NameLoad NameLoad NameLoad decorator_list FunctionDef arguments args NameParam defaults vararg kwarg body Expr Str Assign NameStore Call AttributeLoad NameLoad attr NameLoad Assign NameStore Call NameLoad NameLoad Return Call NameLoad NameLoad NameLoad NameLoad decorator_list FunctionDef arguments args NameParam defaults body Expr Str Assign NameStore Call AttributeLoad NameLoad attr NameLoad While BoolOpAnd NameLoad Call NameLoad SubscriptLoad NameLoad Index Num body Expr Call AttributeLoad NameLoad attr Num While BoolOpAnd NameLoad Call NameLoad SubscriptLoad NameLoad Index Num body Expr Call AttributeLoad NameLoad attr Num Return Call AttributeLoad Str attr NameLoad decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return BoolOpOr CompareEq Call NameLoad NameLoad Num Call AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str Assign NameStore ListLoad For NameStore Call AttributeLoad NameLoad attr Str body Assign NameStore Call NameLoad NameLoad If BoolOpAnd NameLoad UnaryOpNot Call AttributeLoad NameLoad attr body Expr Call AttributeLoad NameLoad attr NameLoad Return NameLoad decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return Call AttributeLoad NameLoad attr Str Str NameLoad decorator_list FunctionDef arguments args NameParam NameParam NameParam defaults NameLoad body Expr Str If UnaryOpNot NameLoad body Assign NameStore BinOpAdd NameLoad Str Return BinOpMod Str TupleLoad NameLoad IfExp CompareEq Call AttributeLoad NameLoad attr Call NameLoad NameLoad Num NameLoad NameLoad decorator_list FunctionDef arguments args NameParam NameParam defaults Str body Expr Str Return ListComp Call AttributeLoad NameLoad attr comprehension NameStore Call AttributeLoad NameLoad attr NameLoad BoolOpAnd NameLoad UnaryOpNot Call AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str Assign NameStore ListLoad For NameStore Call AttributeLoad NameLoad attr Str NameLoad body Assign NameStore Call AttributeLoad NameLoad attr If Call AttributeLoad NameLoad attr Str NameLoad body Expr Call AttributeLoad NameLoad attr Call NameLoad NameLoad orelse If Call AttributeLoad NameLoad attr body Expr Call AttributeLoad NameLoad attr Call NameLoad NameLoad orelse If NameLoad body Expr Call AttributeLoad NameLoad attr NameLoad Return NameLoad decorator_list
N/A N/A 
Simple text manipulation functions.

The :mod:`~humanfriendly.text` module contains simple functions to manipulate text:

- The :func:`concatenate()` and :func:`pluralize()` functions make it easy to
  generate human friendly output.

- The :func:`format()`, :func:`compact()` and :func:`dedent()` functions
  provide a clean and simple to use syntax for composing large text fragments
  with interpolated variables.

- The :func:`tokenize()` function parses simple user input.
 N/A math N/A re N/A textwrap concatenate N/A N/A items N/A N/A N/A 
    Concatenate a list of items in a human friendly way.

    :param items: A sequence of strings.
    :returns: A single string.

    >>> from humanfriendly.text import concatenate
    >>> concatenate(["eggs", "milk", "bread"])
    'eggs, milk and bread'
     N/A items N/A list items N/A N/A N/A len items 1 N/A N/A N/A N/A N/A N/A ,  join N/A items N/A -1  and  N/A items N/A -1 N/A N/A items N/A N/A N/A items N/A 0 N/A N/A N/A format N/A N/A text N/A args kw N/A N/A 
    Format a string using the string formatting operator and/or :func:`str.format()`.

    :param text: The text to format (a string).
    :param args: Any positional arguments are interpolated into the text using
                 the string formatting operator (``%``). If no positional
                 arguments are given no interpolation is done.
    :param kw: Any keyword arguments are interpolated into the text using the
               :func:`str.format()` function. If no keyword arguments are given
               no interpolation is done.
    :returns: The text with any positional and/or keyword arguments
              interpolated (a string).

    The implementation of this function is so trivial that it seems silly to
    even bother writing and documenting it. Justifying this requires some
    context :-).

    **Why format() instead of the string formatting operator?**

    For really simple string interpolation Python's string formatting operator
    is ideal, but it does have some strange quirks:

    - When you switch from interpolating a single value to interpolating
      multiple values you have to wrap them in tuple syntax. Because
      :func:`format()` takes a `variable number of arguments`_ it always
      receives a tuple (which saves me a context switch :-). Here's an
      example:

      >>> from humanfriendly.text import format
      >>> # The string formatting operator.
      >>> print('the magic number is %s' % 42)
      the magic number is 42
      >>> print('the magic numbers are %s and %s' % (12, 42))
      the magic numbers are 12 and 42
      >>> # The format() function.
      >>> print(format('the magic number is %s', 42))
      the magic number is 42
      >>> print(format('the magic numbers are %s and %s', 12, 42))
      the magic numbers are 12 and 42

    - When you interpolate a single value and someone accidentally passes in a
      tuple your code raises a :exc:`~exceptions.TypeError`. Because
      :func:`format()` takes a `variable number of arguments`_ it always
      receives a tuple so this can never happen. Here's an example:

      >>> # How expecting to interpolate a single value can fail.
      >>> value = (12, 42)
      >>> print('the magic value is %s' % value)
      Traceback (most recent call last):
        File "<stdin>", line 1, in <module>
      TypeError: not all arguments converted during string formatting
      >>> # The following line works as intended, no surprises here!
      >>> print(format('the magic value is %s', value))
      the magic value is (12, 42)

    **Why format() instead of the str.format() method?**

    When you're doing complex string interpolation the :func:`str.format()`
    function results in more readable code, however I frequently find myself
    adding parentheses to force evaluation order. The :func:`format()` function
    avoids this because of the relative priority between the comma and dot
    operators. Here's an example:

    >>> "{adjective} example" + " " + "(can't think of anything less {adjective})".format(adjective='silly')
    "{adjective} example (can't think of anything less silly)"
    >>> ("{adjective} example" + " " + "(can't think of anything less {adjective})").format(adjective='silly')
    "silly example (can't think of anything less silly)"
    >>> format("{adjective} example" + " " + "(can't think of anything less {adjective})", adjective='silly')
    "silly example (can't think of anything less silly)"

    The :func:`compact()` and :func:`dedent()` functions are wrappers that
    combine :func:`format()` with whitespace manipulation to make it easy to
    write nice to read Python code.

    .. _variable number of arguments: https://docs.python.org/2/tutorial/controlflow.html#arbitrary-argument-lists
     N/A args N/A N/A text args N/A kw N/A N/A text N/A N/A text format kw N/A text N/A compact N/A N/A text N/A args kw N/A N/A 
    Compact whitespace in a string.

    Trims leading and trailing whitespace, replaces runs of whitespace
    characters with a single space and interpolates any arguments using
    :func:`format()`.

    :param text: The text to compact (a string).
    :param args: Any positional arguments are interpolated using :func:`format()`.
    :param kw: Any keyword arguments are interpolated using :func:`format()`.
    :returns: The compacted text (a string).

    Here's an example of how I like to use the :func:`compact()` function, this
    is an example from a random unrelated project I'm working on at the moment::

        raise PortDiscoveryError(compact("""
            Failed to discover port(s) that Apache is listening on!
            Maybe I'm parsing the wrong configuration file? ({filename})
        """, filename=self.ports_config))

    The combination of :func:`compact()` and Python's multi line strings allows
    me to write long text fragments with interpolated variables that are easy
    to write, easy to read and work well with Python's whitespace
    sensitivity.
     N/A non_whitespace_tokens N/A N/A text split N/A compacted_text N/A N/A join non_whitespace_tokens N/A N/A format compacted_text args kw N/A dedent N/A N/A text N/A args kw N/A N/A 
    Dedent a string (remove common leading whitespace from all lines).

    Removes common leading whitespace from all lines in the string using
    :func:`textwrap.dedent()`, removes leading and trailing empty lines using
    :func:`trim_empty_lines()` and interpolates any arguments using
    :func:`format()`.

    :param text: The text to dedent (a string).
    :param args: Any positional arguments are interpolated using :func:`format()`.
    :param kw: Any keyword arguments are interpolated using :func:`format()`.
    :returns: The dedented text (a string).

    The :func:`compact()` function's documentation contains an example of how I
    like to use the :func:`compact()` and :func:`dedent()` functions. The main
    difference is that I use :func:`compact()` for text that will be presented
    to the user (where whitespace is not so significant) and :func:`dedent()`
    for data file and code generation tasks (where newlines and indentation are
    very significant).
     N/A dedented_text N/A N/A textwrap dedent text N/A trimmed_text N/A trim_empty_lines dedented_text N/A N/A format trimmed_text args kw N/A trim_empty_lines N/A N/A text N/A N/A N/A 
    Trim leading and trailing empty lines from the given text.

    :param text: The text to trim (a string).
    :returns: The trimmed text (a string).
     N/A lines N/A N/A text splitlines True N/A N/A lines N/A is_empty_line N/A lines N/A 0 N/A N/A N/A N/A lines pop 0 N/A N/A lines N/A is_empty_line N/A lines N/A -1 N/A N/A N/A N/A lines pop -1 N/A N/A N/A join lines N/A is_empty_line N/A N/A text N/A N/A N/A 
    Check if a text is empty or contains only whitespace.

    :param text: The text to check for "emptiness" (a string).
    :returns: :data:`True` if the text is empty or contains only whitespace,
              :data:`False` otherwise.
     N/A N/A N/A N/A len text 0 N/A N/A text isspace N/A split_paragraphs N/A N/A text N/A N/A N/A 
    Split a string into paragraphs (one or more lines delimited by an empty line).

    :param text: The text to split into paragraphs (a string).
    :returns: A list of strings.
     N/A paragraphs N/A N/A chunk N/A N/A text split N/A N/A chunk N/A trim_empty_lines chunk N/A N/A chunk N/A N/A N/A chunk isspace N/A N/A N/A N/A paragraphs append chunk N/A paragraphs N/A join_lines N/A N/A text N/A N/A N/A 
    Remove "hard wrapping" from the paragraphs in a string.

    :param text: The text to reformat (a string).
    :returns: The text without hard wrapping (a string).

    This function works by removing line breaks when the last character before
    a line break and the first character after the line break are both
    non-whitespace characters. This means that common leading indentation will
    break :func:`join_lines()` (in that case you can use :func:`dedent()`
    before calling :func:`join_lines()`).
     N/A N/A N/A re sub (\S)\n(\S) \1 \2 text N/A pluralize N/A N/A count singular plural N/A None N/A N/A 
    Combine a count with the singular or plural form of a word.

    If the plural form of the word is not provided it is obtained by
    concatenating the singular form of the word with the letter "s". Of course
    this will not always be correct, which is why you have the option to
    specify both forms.

    :param count: The count (a number).
    :param singular: The singular form of the word (a string).
    :param plural: The plural form of the word (a string or ``None``).
    :returns: The count and singular/plural word concatenated (a string).
     N/A N/A plural N/A N/A plural N/A singular s N/A N/A %s %s N/A count N/A N/A N/A N/A math floor N/A float count 1 singular plural N/A split N/A N/A text delimiter N/A , N/A N/A 
    Split a comma-separated list of strings.

    :param text: The text to split (a string).
    :param delimiter: The delimiter to split on (a string).
    :returns: A list of zero or more nonempty strings.

    Here's the default behavior of Python's built in :func:`str.split()`
    function:

    >>> 'foo,bar, baz,'.split(',')
    ['foo', 'bar', ' baz', '']

    In contrast here's the default behavior of the :func:`split()` function:

    >>> from humanfriendly.text import split
    >>> split('foo,bar, baz,')
    ['foo', 'bar', 'baz']

    Here is an example that parses a nested data structure (a mapping of
    logging level names to one or more styles per level) that's encoded in a
    string so it can be set as an environment variable:

    >>> from pprint import pprint
    >>> encoded_data = 'debug=green;warning=yellow;error=red;critical=red,bold'
    >>> parsed_data = dict((k, split(v, ',')) for k, v in (split(kv, '=') for kv in split(encoded_data, ';')))
    >>> pprint(parsed_data)
    {'debug': ['green'],
     'warning': ['yellow'],
     'error': ['red'],
     'critical': ['red', 'bold']}
     N/A N/A N/A N/A token strip N/A token N/A N/A text split delimiter N/A token N/A N/A N/A token isspace N/A tokenize N/A N/A text N/A N/A N/A 
    Tokenize a text into numbers and strings.

    :param text: The text to tokenize (a string).
    :returns: A list of strings and/or numbers.

    This function is used to implement robust tokenization of user input in
    functions like :func:`.parse_size()` and :func:`.parse_timespan()`. It
    automatically coerces integer and floating point numbers, ignores
    whitespace and knows how to separate numbers from strings even without
    whitespace. Some examples to make this more concrete:

    >>> from humanfriendly.text import tokenize
    >>> tokenize('42')
    [42]
    >>> tokenize('42MB')
    [42, 'MB']
    >>> tokenize('42.5MB')
    [42.5, 'MB']
    >>> tokenize('42.5 MB')
    [42.5, 'MB']
     N/A tokenized_input N/A N/A token N/A N/A re split (\d+(?:\.\d+)?) text N/A N/A token N/A N/A token strip N/A N/A N/A re match \d+\.\d+ token N/A N/A N/A N/A tokenized_input append N/A float token N/A N/A N/A N/A token isdigit N/A N/A N/A N/A tokenized_input append N/A int token N/A N/A token N/A N/A N/A N/A tokenized_input append token N/A tokenized_input N/A