--- /tmp/humanfriendly-9.1-16v2amai8/debian/python-humanfriendly-doc_9.1-1_all.deb +++ python-humanfriendly-doc_9.1-1_all.deb ├── file list │ @@ -1,3 +1,3 @@ │ -rw-r--r-- 0 0 0 4 2021-01-10 04:22:01.000000 debian-binary │ --rw-r--r-- 0 0 0 1656 2021-01-10 04:22:01.000000 control.tar.xz │ --rw-r--r-- 0 0 0 367396 2021-01-10 04:22:01.000000 data.tar.xz │ +-rw-r--r-- 0 0 0 1652 2021-01-10 04:22:01.000000 control.tar.xz │ +-rw-r--r-- 0 0 0 367416 2021-01-10 04:22:01.000000 data.tar.xz ├── control.tar.xz │ ├── control.tar │ │ ├── ./control │ │ │ @@ -1,13 +1,13 @@ │ │ │ Package: python-humanfriendly-doc │ │ │ Source: humanfriendly │ │ │ Version: 9.1-1 │ │ │ Architecture: all │ │ │ Maintainer: Debian Python Team │ │ │ -Installed-Size: 1141 │ │ │ +Installed-Size: 1142 │ │ │ Depends: libjs-sphinxdoc (>= 2.4.3-5~) │ │ │ Section: doc │ │ │ Priority: optional │ │ │ Homepage: https://humanfriendly.readthedocs.io │ │ │ Description: Python3 library to make user friendly text interfaces - Documentation │ │ │ A Python3 library that can be used to make text interfaces more user friendly. │ │ │ It provides parsing and formatting numbers, file sizes, pathnames and │ │ ├── ./md5sums │ │ │ ├── ./md5sums │ │ │ │┄ Files differ ├── data.tar.xz │ ├── data.tar │ │ ├── file list │ │ │ @@ -23,15 +23,15 @@ │ │ │ -rw-r--r-- 0 root (0) root (0) 13647 2021-01-10 04:22:01.000000 ./usr/share/doc/python-humanfriendly-doc/html/_static/basic.css │ │ │ -rw-r--r-- 0 root (0) root (0) 351 2021-01-10 04:22:01.000000 ./usr/share/doc/python-humanfriendly-doc/html/_static/documentation_options.js │ │ │ -rw-r--r-- 0 root (0) root (0) 286 2021-01-01 06:53:29.000000 ./usr/share/doc/python-humanfriendly-doc/html/_static/file.png │ │ │ -rw-r--r-- 0 root (0) root (0) 90 2021-01-01 06:53:29.000000 ./usr/share/doc/python-humanfriendly-doc/html/_static/minus.png │ │ │ -rw-r--r-- 0 root (0) root (0) 4181 2021-01-10 04:22:01.000000 ./usr/share/doc/python-humanfriendly-doc/html/_static/nature.css │ │ │ -rw-r--r-- 0 root (0) root (0) 90 2021-01-01 06:53:29.000000 ./usr/share/doc/python-humanfriendly-doc/html/_static/plus.png │ │ │ -rw-r--r-- 0 root (0) root (0) 4780 2021-01-10 04:22:01.000000 ./usr/share/doc/python-humanfriendly-doc/html/_static/pygments.css │ │ │ --rw-r--r-- 0 root (0) root (0) 619309 2021-01-10 04:22:01.000000 ./usr/share/doc/python-humanfriendly-doc/html/api.html │ │ │ +-rw-r--r-- 0 root (0) root (0) 619562 2021-01-10 04:22:01.000000 ./usr/share/doc/python-humanfriendly-doc/html/api.html │ │ │ -rw-r--r-- 0 root (0) root (0) 22756 2021-01-10 04:22:01.000000 ./usr/share/doc/python-humanfriendly-doc/html/changelog.html.gz │ │ │ -rw-r--r-- 0 root (0) root (0) 53901 2021-01-10 04:22:01.000000 ./usr/share/doc/python-humanfriendly-doc/html/genindex.html │ │ │ -rw-r--r-- 0 root (0) root (0) 28246 2021-01-10 04:22:01.000000 ./usr/share/doc/python-humanfriendly-doc/html/index.html │ │ │ -rw-r--r-- 0 root (0) root (0) 2718 2021-01-10 04:22:01.000000 ./usr/share/doc/python-humanfriendly-doc/html/objects.inv │ │ │ -rw-r--r-- 0 root (0) root (0) 6543 2021-01-10 04:22:01.000000 ./usr/share/doc/python-humanfriendly-doc/html/py-modindex.html │ │ │ -rw-r--r-- 0 root (0) root (0) 19034 2021-01-10 04:22:01.000000 ./usr/share/doc/python-humanfriendly-doc/html/readme.html │ │ │ -rw-r--r-- 0 root (0) root (0) 3303 2021-01-10 04:22:01.000000 ./usr/share/doc/python-humanfriendly-doc/html/search.html │ │ ├── ./usr/share/doc/python-humanfriendly-doc/html/api.html │ │ │ @@ -368,19 +368,19 @@ │ │ │
│ │ │ __init__(start_time=None, resumable=False)
│ │ │

Remember the time when the Timer was created.

│ │ │
│ │ │
Parameters
│ │ │
    │ │ │

  • start_time – The start time (a float, defaults to the current time).

    • │ │ │ -

  • resumable – Create a resumable timer (defaults to False).

    • │ │ │ +

  • resumable – Create a resumable timer (defaults to False).

    • │ │ │
│ │ │
│ │ │
│ │ │ -

When start_time is given Timer uses time.time() as a │ │ │ +

When start_time is given Timer uses time.time() as a │ │ │ clock source, otherwise it uses humanfriendly.compat.monotonic().

│ │ │
│ │ │ │ │ │
│ │ │
│ │ │ __enter__()
│ │ │

Start or resume counting elapsed time.

│ │ │ @@ -413,19 +413,19 @@ │ │ │
Parameters
│ │ │

seconds – The number of seconds to sleep (an │ │ │ integer or floating point number).

│ │ │
│ │ │
│ │ │

This method sleeps for the given number of seconds minus the │ │ │ elapsed_time. If the resulting duration is negative │ │ │ -time.sleep() will still be called, but the argument │ │ │ +time.sleep() will still be called, but the argument │ │ │ given to it will be the number 0 (negative numbers cause │ │ │ -time.sleep() to raise an exception).

│ │ │ +time.sleep() to raise an exception).

│ │ │

The use case for this is to initialize a Timer inside │ │ │ -the body of a for or while loop and call │ │ │ +the body of a for or while loop and call │ │ │ Timer.sleep() at the end of the loop body to rate limit │ │ │ whatever it is that is being done inside the loop body.

│ │ │

For posterity: Although the implementation of sleep() only │ │ │ requires a single line of code I’ve added it to humanfriendly │ │ │ anyway because now that I’ve thought about how to tackle this once I │ │ │ never want to have to think about it again :-P (unless I find ways to │ │ │ improve this).

│ │ │ @@ -455,19 +455,19 @@ │ │ │
│ │ │ humanfriendly.coerce_boolean(value)
│ │ │

Coerce any value to a boolean.

│ │ │
│ │ │
Parameters
│ │ │

value –

Any Python value. If the value is a string:

│ │ │
    │ │ │ -

  • The strings ‘1’, ‘yes’, ‘true’ and ‘on’ are coerced to True.

    • │ │ │ -

  • The strings ‘0’, ‘no’, ‘false’ and ‘off’ are coerced to False.

    • │ │ │ +

  • The strings ‘1’, ‘yes’, ‘true’ and ‘on’ are coerced to True.

    • │ │ │ +

  • The strings ‘0’, ‘no’, ‘false’ and ‘off’ are coerced to False.

    • │ │ │

  • Other strings raise an exception.

    • │ │ │
│ │ │ -

Other Python values are coerced using bool.

│ │ │ +

Other Python values are coerced using bool.

│ │ │

│ │ │
│ │ │
Returns
│ │ │

A proper boolean value.

│ │ │
│ │ │
Raises
│ │ │

exceptions.ValueError when the value is a string but │ │ │ @@ -500,35 +500,35 @@ │ │ │ │ │ │

│ │ │
│ │ │ humanfriendly.coerce_seconds(value)
│ │ │

Coerce a value to the number of seconds.

│ │ │
│ │ │
Parameters
│ │ │ -

value – An int, float or │ │ │ -datetime.timedelta object.

│ │ │ +

value – An int, float or │ │ │ +datetime.timedelta object.

│ │ │
│ │ │
Returns
│ │ │ -

An int or float value.

│ │ │ +

An int or float value.

│ │ │
│ │ │
│ │ │ -

When value is a datetime.timedelta object the │ │ │ -total_seconds() method is called.

│ │ │ +

When value is a datetime.timedelta object the │ │ │ +total_seconds() method is called.

│ │ │
│ │ │ │ │ │
│ │ │
│ │ │ humanfriendly.format_length(num_metres, keep_width=False)
│ │ │

Format a metre count as a human readable length.

│ │ │
│ │ │
Parameters
│ │ │
    │ │ │

  • num_metres – The length to format in metres (float / integer).

    • │ │ │ -

  • keep_width – True if trailing zeros should not be stripped, │ │ │ -False if they can be stripped.

    • │ │ │ +

  • keep_width – True if trailing zeros should not be stripped, │ │ │ +False if they can be stripped.

    • │ │ │
│ │ │
│ │ │
Returns
│ │ │

The corresponding human readable length (a string).

│ │ │
│ │ │
│ │ │

This function supports ranges from nanometres to kilometres.

│ │ │ @@ -551,16 +551,16 @@ │ │ │
│ │ │
│ │ │ humanfriendly.format_number(number, num_decimals=2)
│ │ │

Format a number as a string including thousands separators.

│ │ │
│ │ │
Parameters
│ │ │
    │ │ │ -

  • number – The number to format (a number like an int, │ │ │ -long or float).

    • │ │ │ +

  • number – The number to format (a number like an int, │ │ │ +long or float).

    • │ │ │

  • num_decimals – The number of decimals to render (2 by default). If no │ │ │ decimal places are required to represent the number │ │ │ they will be omitted regardless of this argument.

    • │ │ │
│ │ │
│ │ │
Returns
│ │ │

The formatted number (a string).

│ │ │ @@ -613,18 +613,18 @@ │ │ │
│ │ │ humanfriendly.format_size(num_bytes, keep_width=False, binary=False)
│ │ │

Format a byte count as a human readable file size.

│ │ │
│ │ │
Parameters
│ │ │
    │ │ │

  • num_bytes – The size to format in bytes (an integer).

    • │ │ │ -

  • keep_width – True if trailing zeros should not be stripped, │ │ │ -False if they can be stripped.

    • │ │ │ -

  • binary – True to use binary multiples of bytes (base-2), │ │ │ -False to use decimal multiples of bytes (base-10).

    • │ │ │ +

  • keep_width – True if trailing zeros should not be stripped, │ │ │ +False if they can be stripped.

    • │ │ │ +

  • binary – True to use binary multiples of bytes (base-2), │ │ │ +False to use decimal multiples of bytes (base-10).

    • │ │ │
│ │ │
│ │ │
Returns
│ │ │

The corresponding human readable file size (a string).

│ │ │
│ │ │
│ │ │

This function knows how to format sizes in bytes, kilobytes, megabytes, │ │ │ @@ -650,17 +650,17 @@ │ │ │

│ │ │ humanfriendly.format_timespan(num_seconds, detailed=False, max_units=3)
│ │ │

Format a timespan in seconds as a human readable string.

│ │ │
│ │ │
Parameters
│ │ │
    │ │ │

  • num_seconds – Any value accepted by coerce_seconds().

    • │ │ │ -

  • detailed – If True milliseconds are represented separately │ │ │ +

  • detailed – If True milliseconds are represented separately │ │ │ instead of being represented as fractional seconds │ │ │ -(defaults to False).

    • │ │ │ +(defaults to False).

    │ │ │

  • max_units – The maximum number of units to show in the formatted time │ │ │ span (an integer, defaults to three).

    • │ │ │
│ │ │
│ │ │
Returns
│ │ │

The formatted timespan as a string.

│ │ │
│ │ │ @@ -707,15 +707,15 @@ │ │ │

  • YYYY-MM-DD

    • │ │ │

  • YYYY-MM-DD HH:MM:SS

    • │ │ │ │ │ │
    │ │ │

    Note

    │ │ │

    If you want to parse date/time strings with a fixed, known │ │ │ format and parse_date() isn’t useful to you, consider │ │ │ -time.strptime() or datetime.datetime.strptime(), │ │ │ +time.strptime() or datetime.datetime.strptime(), │ │ │ both of which are included in the Python standard library. │ │ │ Alternatively for more complex tasks consider using the date/time │ │ │ parsing module in the dateutil package.

    │ │ │
    │ │ │

    Examples:

    │ │ │ 
    >>> from humanfriendly import parse_date
│ │ │  >>> parse_date('2013-06-17')
│ │ │ @@ -727,15 +727,15 @@
│ │ │  
    Here’s how you convert the result to a number (Unix time):
    
│ │ │  
    >>> from humanfriendly import parse_date
│ │ │  >>> from time import mktime
│ │ │  >>> mktime(parse_date('2013-06-17 02:47:42') + (-1, -1, -1))
│ │ │  1371430062.0
│ │ │  
    
│ │ │  
    
│ │ │ -
    And here’s how you convert it to a datetime.datetime object:
    
│ │ │ +
    And here’s how you convert it to a datetime.datetime object:
    
│ │ │  
    >>> from humanfriendly import parse_date
│ │ │  >>> from datetime import datetime
│ │ │  >>> datetime(*parse_date('2013-06-17 02:47:42'))
│ │ │  datetime.datetime(2013, 6, 17, 2, 47, 42)
│ │ │  
    
│ │ │  
    
│ │ │  
    Here’s an example that combines format_timespan() and
│ │ │ @@ -780,17 +780,17 @@
│ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.parse_path(pathname)
    │ │ │

    Convert a human friendly pathname to an absolute pathname.

    │ │ │ -

    Expands leading tildes using os.path.expanduser() and │ │ │ -environment variables using os.path.expandvars() and makes the │ │ │ -resulting pathname absolute using os.path.abspath().

    │ │ │ +

    Expands leading tildes using os.path.expanduser() and │ │ │ +environment variables using os.path.expandvars() and makes the │ │ │ +resulting pathname absolute using os.path.abspath().

    │ │ │
    │ │ │
    Parameters
    │ │ │

    pathname – A human friendly pathname (a string).

    │ │ │
    │ │ │
    Returns
    │ │ │

    An absolute pathname (a string).

    │ │ │
    │ │ │ @@ -801,16 +801,16 @@ │ │ │
    │ │ │ humanfriendly.parse_size(size, binary=False)
    │ │ │

    Parse a human readable data size and return the number of bytes.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • size – The human readable file size to parse (a string).

      • │ │ │ -

    • binary – True to use binary multiples of bytes (base-2) for │ │ │ -ambiguous unit symbols and names, False to use │ │ │ +

    • binary – True to use binary multiples of bytes (base-2) for │ │ │ +ambiguous unit symbols and names, False to use │ │ │ decimal multiples of bytes (base-10).

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    The corresponding size in bytes (an integer).

    │ │ │
    │ │ │
    Raises
    │ │ │ @@ -893,16 +893,16 @@ │ │ │
    │ │ │ humanfriendly.round_number(count, keep_width=False)
    │ │ │

    Round a floating point number to two decimal places in a human friendly format.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • count – The number to format.

      • │ │ │ -

    • keep_width – True if trailing zeros should not be stripped, │ │ │ -False if they can be stripped.

      • │ │ │ +

    • keep_width – True if trailing zeros should not be stripped, │ │ │ +False if they can be stripped.

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    The formatted number as a string. If no decimal places are │ │ │ required to represent the number, they will be omitted.

    │ │ │
    │ │ │
    │ │ │ @@ -959,16 +959,16 @@ │ │ │ humanfriendly.concatenate(items, conjunction='and', serial_comma=False) │ │ │

    Concatenate a list of items in a human friendly way.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • items – A sequence of strings.

      • │ │ │

    • conjunction – The word to use before the last item (a string, defaults to “and”).

      • │ │ │ -

    • serial_comma – True to use a serial comma, False otherwise │ │ │ -(defaults to False).

      • │ │ │ +

    • serial_comma – True to use a serial comma, False otherwise │ │ │ +(defaults to False).

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    A single string.

    │ │ │
    │ │ │
    │ │ │ 
    >>> from humanfriendly.text import concatenate
│ │ │ @@ -979,15 +979,15 @@
│ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.dedent(text, *args, **kw)
    │ │ │

    Dedent a string (remove common leading whitespace from all lines).

    │ │ │

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

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • text – The text to dedent (a string).

      • │ │ │

    • args – Any positional arguments are interpolated using format().

      • │ │ │ @@ -1017,37 +1017,37 @@ │ │ │

    • aliases – Each keyword argument defines an alias. The values │ │ │ are expected to be “dotted paths” (strings).

      • │ │ │
    │ │ │
    │ │ │
    │ │ │

    The behavior of this function depends on whether the Sphinx documentation │ │ │ generator is active, because the use of DeprecationProxy to shadow the │ │ │ -real module in sys.modules has the unintended side effect of │ │ │ +real module in sys.modules has the unintended side effect of │ │ │ breaking autodoc support for :data: members (module variables).

    │ │ │

    To avoid breaking Sphinx the proxy object is omitted and instead the │ │ │ aliased names are injected into the original module namespace, to make sure │ │ │ that imports can be satisfied when the documentation is being rendered.

    │ │ │

    If you run into cyclic dependencies caused by define_aliases() when │ │ │ running Sphinx, you can try moving the call to define_aliases() to │ │ │ the bottom of the Python module you’re working on.

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.format(text, *args, **kw)
    │ │ │ -

    Format a string using the string formatting operator and/or str.format().

    │ │ │ +

    Format a string using the string formatting operator and/or str.format().

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • text – The text to format (a string).

      • │ │ │

    • args – Any positional arguments are interpolated into the text using │ │ │ the string formatting operator (%). If no positional │ │ │ arguments are given no interpolation is done.

      • │ │ │

    • kw – Any keyword arguments are interpolated into the text using the │ │ │ -str.format() function. If no keyword arguments are given │ │ │ +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).

    │ │ │
    │ │ │ @@ -1092,15 +1092,15 @@ │ │ │ >>> 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 str.format() │ │ │ +

    When you’re doing complex string interpolation the str.format() │ │ │ function results in more readable code, however I frequently find myself │ │ │ adding parentheses to force evaluation order. The 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')
│ │ │ @@ -1117,15 +1117,15 @@
│ │ │  
    
│ │ │  
    
│ │ │  humanfriendly.format_table(data, column_names=None, horizontal_bar='-', vertical_bar='|')
    
│ │ │  
    Render a table using characters like dashes and vertical bars to emulate borders.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
      
│ │ │ -
    • data – An iterable (e.g. a tuple() or list)
│ │ │ +
    • data – An iterable (e.g. a tuple() or list)
│ │ │  containing the rows of the table, where each row is an
│ │ │  iterable containing the columns of the table (strings).
      • 
│ │ │  
    • column_names – An iterable of column names (strings).
      • 
│ │ │  
    • horizontal_bar – The character used to represent a horizontal bar (a
│ │ │  string).
      • 
│ │ │  
    • vertical_bar – The character used to represent a vertical bar (a
│ │ │  string).
      • 
│ │ │ @@ -1178,44 +1178,44 @@
│ │ │  humanfriendly.is_empty_line(text)
│ │ │  
      Check if a text is empty or contains only whitespace.
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
      text – The text to check for “emptiness” (a string).
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │ -
      True if the text is empty or contains only whitespace,
│ │ │ -False otherwise.
      
│ │ │ +
      True if the text is empty or contains only whitespace,
│ │ │ +False otherwise.
      
│ │ │  
      
│ │ │  
      
│ │ │  
    
│ │ │  
│ │ │  
    
│ │ │  
    
│ │ │  humanfriendly.is_string(value)
    
│ │ │ -
    Check if a value is a basestring() (in Python 2) or str (in Python 3) object.
    
│ │ │ +
    Check if a value is a basestring() (in Python 2) or str (in Python 3) object.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
    value – The value to check.
    
│ │ │  
    
│ │ │  
    Returns
    
│ │ │ -
    True if the value is a string, False otherwise.
    
│ │ │ +
    True if the value is a string, False otherwise.
    
│ │ │  
    
│ │ │  
    
│ │ │  
    
│ │ │  
│ │ │  
    
│ │ │  
    
│ │ │  humanfriendly.pluralize(count, singular, plural=None)
    
│ │ │  
    Combine a count with the singular or plural form of a word.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
      
│ │ │  
    • count – The count (a number).
      • 
│ │ │  
    • singular – The singular form of the word (a string).
      • 
│ │ │ -
    • plural – The plural form of the word (a string or None).
      • 
│ │ │ +
    • plural – The plural form of the word (a string or None).
      • 
│ │ │  
    
│ │ │  
    
│ │ │  
    Returns
    
│ │ │  
    The count and singular or plural word concatenated (a string).
    
│ │ │  
    
│ │ │  
    
│ │ │  
    See pluralize_raw() for the logic underneath pluralize().
    
│ │ │ @@ -1226,15 +1226,15 @@
│ │ │  humanfriendly.prompt_for_choice(choices, default=None, padding=True)
│ │ │  
    Prompt the user to select a choice from a group of options.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
      
│ │ │  
    • choices – A sequence of strings with available options.
      • 
│ │ │  
    • default – The default choice if the user simply presses Enter
│ │ │ -(expected to be a string, defaults to None).
      • 
│ │ │ +(expected to be a string, defaults to None).
      
│ │ │  
    • padding – Refer to the documentation of
│ │ │  prompt_for_input().
      • 
│ │ │  
    
│ │ │  
    
│ │ │  
    Returns
    
│ │ │  
    The string corresponding to the user’s choice.
    
│ │ │  
    
│ │ │ @@ -1594,15 +1594,15 @@
│ │ │  humanfriendly.cli.ansi_strip(text, readline_hints=True)
│ │ │  
    Strip ANSI escape sequences from the given string.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
      
│ │ │  
    • text – The text from which ANSI escape sequences should be removed (a
│ │ │  string).
      • 
│ │ │ -
    • readline_hints – If True then readline_strip() is
│ │ │ +
    • readline_hints – If True then readline_strip() is
│ │ │  used to remove readline hints from the string.
      • 
│ │ │  
    
│ │ │  
    
│ │ │  
    Returns
    
│ │ │  
    The text without ANSI escape sequences (a string).
    
│ │ │  
    
│ │ │  
    
│ │ │ @@ -1636,22 +1636,22 @@
│ │ │  
│ │ │  
    
│ │ │  
    
│ │ │  humanfriendly.cli.enable_ansi_support()
    
│ │ │  
    Try to enable support for ANSI escape sequences (required on Windows).
    
│ │ │  
    
│ │ │  
    Returns
    
│ │ │ -
    True if ANSI is supported, False otherwise.
    
│ │ │ +
    True if ANSI is supported, False otherwise.
    
│ │ │  
    
│ │ │  
    
│ │ │  
    This functions checks for the following supported configurations, in the
│ │ │  given order:
    
│ │ │  
      
│ │ │  
    1. On Windows, if have_windows_native_ansi_support() confirms
│ │ │ -native support for ANSI escape sequences ctypes will be used to
│ │ │ +native support for ANSI escape sequences ctypes will be used to
│ │ │  enable this support.
      2. 
│ │ │  
    2. On Windows, if the environment variable $ANSICON is set nothing is
│ │ │  done because it is assumed that support for ANSI escape sequences has
│ │ │  already been enabled via ansicon.
      3. 
│ │ │  
    3. On Windows, an attempt is made to import and initialize the Python
│ │ │  package colorama instead (of course for this to work
│ │ │  colorama has to be installed).
      4. 
│ │ │ @@ -1687,15 +1687,15 @@
│ │ │  
      
│ │ │  
      Note
      
│ │ │  
      The find_terminal_size() function performs the steps
│ │ │  above every time it is called, the result is not cached. This is
│ │ │  because the size of a virtual terminal can change at any time and
│ │ │  the result of find_terminal_size() should be correct.
      
│ │ │  
      Pre-emptive snarky comment: It’s possible to cache the result
│ │ │ -of this function and use signal.SIGWINCH to
│ │ │ +of this function and use signal.SIGWINCH to
│ │ │  refresh the cached values!
      
│ │ │  
      Response: As a library I don’t consider it the role of the
│ │ │  humanfriendly.terminal module to install a process wide
│ │ │  signal handler …
      
│ │ │  
      
│ │ │  
    
│ │ │  
│ │ │ @@ -1703,16 +1703,16 @@
│ │ │  
    
│ │ │  humanfriendly.cli.format_length(num_metres, keep_width=False)
    
│ │ │  
    Format a metre count as a human readable length.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
      
│ │ │  
    • num_metres – The length to format in metres (float / integer).
      • 
│ │ │ -
    • keep_width – True if trailing zeros should not be stripped,
│ │ │ -False if they can be stripped.
      • 
│ │ │ +
    • keep_width – True if trailing zeros should not be stripped,
│ │ │ +False if they can be stripped.
      • 
│ │ │  
    
│ │ │  
    
│ │ │  
    Returns
    
│ │ │  
    The corresponding human readable length (a string).
    
│ │ │  
    
│ │ │  
    
│ │ │  
    This function supports ranges from nanometres to kilometres.
    
│ │ │ @@ -1735,16 +1735,16 @@
│ │ │  
    
│ │ │  
    
│ │ │  humanfriendly.cli.format_number(number, num_decimals=2)
    
│ │ │  
    Format a number as a string including thousands separators.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
      
│ │ │ -
    • number – The number to format (a number like an int,
│ │ │ -long or float).
      • 
│ │ │ +
    • number – The number to format (a number like an int,
│ │ │ +long or float).
      • 
│ │ │  
    • num_decimals – The number of decimals to render (2 by default). If no
│ │ │  decimal places are required to represent the number
│ │ │  they will be omitted regardless of this argument.
      • 
│ │ │  
    
│ │ │  
    
│ │ │  
    Returns
    
│ │ │  
    The formatted number (a string).
    
│ │ │ @@ -1767,15 +1767,15 @@
│ │ │  
    
│ │ │  
    
│ │ │  humanfriendly.cli.format_pretty_table(data, column_names=None, horizontal_bar='-', vertical_bar='|')
    
│ │ │  
    Render a table using characters like dashes and vertical bars to emulate borders.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
      
│ │ │ -
    • data – An iterable (e.g. a tuple() or list)
│ │ │ +
    • data – An iterable (e.g. a tuple() or list)
│ │ │  containing the rows of the table, where each row is an
│ │ │  iterable containing the columns of the table (strings).
      • 
│ │ │  
    • column_names – An iterable of column names (strings).
      • 
│ │ │  
    • horizontal_bar – The character used to represent a horizontal bar (a
│ │ │  string).
      • 
│ │ │  
    • vertical_bar – The character used to represent a vertical bar (a
│ │ │  string).
      • 
│ │ │ @@ -1827,18 +1827,18 @@
│ │ │  
      
│ │ │  humanfriendly.cli.format_size(num_bytes, keep_width=False, binary=False)
      
│ │ │  
      Format a byte count as a human readable file size.
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
        
│ │ │  
      • num_bytes – The size to format in bytes (an integer).
        • 
│ │ │ -
      • keep_width – True if trailing zeros should not be stripped,
│ │ │ -False if they can be stripped.
        • 
│ │ │ -
      • binary – True to use binary multiples of bytes (base-2),
│ │ │ -False to use decimal multiples of bytes (base-10).
        • 
│ │ │ +
      • keep_width – True if trailing zeros should not be stripped,
│ │ │ +False if they can be stripped.
        • 
│ │ │ +
      • binary – True to use binary multiples of bytes (base-2),
│ │ │ +False to use decimal multiples of bytes (base-10).
        • 
│ │ │  
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │  
      The corresponding human readable file size (a string).
      
│ │ │  
      
│ │ │  
      
│ │ │  
      This function knows how to format sizes in bytes, kilobytes, megabytes,
│ │ │ @@ -1863,15 +1863,15 @@
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.cli.format_smart_table(data, column_names)
      
│ │ │  
      Render tabular data using the most appropriate representation.
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
        
│ │ │ -
      • data – An iterable (e.g. a tuple() or list)
│ │ │ +
      • data – An iterable (e.g. a tuple() or list)
│ │ │  containing the rows of the table, where each row is an
│ │ │  iterable containing the columns of the table (strings).
        • 
│ │ │  
      • column_names – An iterable of column names (strings).
        • 
│ │ │  
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │  
      The rendered table (a string).
      
│ │ │ @@ -1895,17 +1895,17 @@
│ │ │  
      
│ │ │  humanfriendly.cli.format_timespan(num_seconds, detailed=False, max_units=3)
      
│ │ │  
      Format a timespan in seconds as a human readable string.
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
        
│ │ │  
      • num_seconds – Any value accepted by coerce_seconds().
        • 
│ │ │ -
      • detailed – If True milliseconds are represented separately
│ │ │ +
      • detailed – If True milliseconds are represented separately
│ │ │  instead of being represented as fractional seconds
│ │ │ -(defaults to False).
        • 
│ │ │ +(defaults to False).
        
│ │ │  
      • max_units – The maximum number of units to show in the formatted time
│ │ │  span (an integer, defaults to three).
        • 
│ │ │  
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │  
      The formatted timespan as a string.
      
│ │ │  
      
│ │ │ @@ -1934,15 +1934,15 @@
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.cli.output(text, *args, **kw)
      
│ │ │  
      Print a formatted message to the standard output stream.
      
│ │ │  
      For details about argument handling please refer to
│ │ │  format().
      
│ │ │  
      Renders the message using format() and writes
│ │ │ -the resulting string (followed by a newline) to sys.stdout using
│ │ │ +the resulting string (followed by a newline) to sys.stdout using
│ │ │  auto_encode().
      
│ │ │  
      
│ │ │  
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.cli.parse_length(length)
      
│ │ │  
      Parse a human readable length and return the number of metres.
      
│ │ │ @@ -1975,16 +1975,16 @@
│ │ │  
      
│ │ │  humanfriendly.cli.parse_size(size, binary=False)
      
│ │ │  
      Parse a human readable data size and return the number of bytes.
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
        
│ │ │  
      • size – The human readable file size to parse (a string).
        • 
│ │ │ -
      • binary – True to use binary multiples of bytes (base-2) for
│ │ │ -ambiguous unit symbols and names, False to use
│ │ │ +
      • binary – True to use binary multiples of bytes (base-2) for
│ │ │ +ambiguous unit symbols and names, False to use
│ │ │  decimal multiples of bytes (base-10).
        • 
│ │ │  
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │  
      The corresponding size in bytes (an integer).
      
│ │ │  
      
│ │ │  
      Raises
      
│ │ │ @@ -2023,132 +2023,132 @@
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
      text – The usage message to print (a string).
      
│ │ │  
      
│ │ │  
      
│ │ │  
      This function does two things:
      
│ │ │  
        
│ │ │ -
      1. If sys.stdout is connected to a terminal (see
│ │ │ +
      2. If sys.stdout is connected to a terminal (see
│ │ │  connected_to_terminal()) then the usage message is formatted
│ │ │  using format_usage().
        3. 
│ │ │  
      3. The usage message is shown using a pager (see show_pager()).
        4. 
│ │ │  
      
│ │ │  
      
│ │ │  
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.cli.warning(text, *args, **kw)
      
│ │ │  
      Show a warning message on the terminal.
      
│ │ │  
      For details about argument handling please refer to
│ │ │  format().
      
│ │ │  
      Renders the message using format() and writes
│ │ │ -the resulting string (followed by a newline) to sys.stderr using
│ │ │ +the resulting string (followed by a newline) to sys.stderr using
│ │ │  auto_encode().
      
│ │ │ -
      If sys.stderr is connected to a terminal that supports colors,
│ │ │ +
      If sys.stderr is connected to a terminal that supports colors,
│ │ │  ansi_wrap() is used to color the message in a red font (to make
│ │ │  the warning stand out from surrounding text).
      
│ │ │  
      
│ │ │  
│ │ │
    │ │ │
    │ │ │

    humanfriendly.compat

    │ │ │

    Compatibility with Python 2 and 3.

    │ │ │

    This module exposes aliases and functions that make it easier to write Python │ │ │ code that is compatible with Python 2 and Python 3.

    │ │ │
    │ │ │
    │ │ │ humanfriendly.compat.basestring
    │ │ │ -

    Alias for basestring() (in Python 2) or str │ │ │ +

    Alias for basestring() (in Python 2) or str │ │ │ (in Python 3). See also is_string().

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.compat.HTMLParser
    │ │ │

    Alias for HTMLParser.HTMLParser (in Python 2) or │ │ │ -html.parser.HTMLParser (in Python 3).

    │ │ │ +html.parser.HTMLParser (in Python 3).

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.compat.interactive_prompt
    │ │ │

    Alias for raw_input() (in Python 2) or │ │ │ -input() (in Python 3).

    │ │ │ +input() (in Python 3).

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.compat.StringIO
    │ │ │

    Alias for StringIO.StringIO (in Python 2) or │ │ │ -io.StringIO (in Python 3).

    │ │ │ +io.StringIO (in Python 3).

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.compat.unicode
    │ │ │ -

    Alias for unicode() (in Python 2) or str (in │ │ │ +

    Alias for unicode() (in Python 2) or str (in │ │ │ Python 3). See also coerce_string().

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.compat.monotonic
    │ │ │ -

    Alias for time.monotonic() (in Python 3.3 and higher) or │ │ │ +

    Alias for time.monotonic() (in Python 3.3 and higher) or │ │ │ monotonic.monotonic() (a conditional dependency on older Python versions).

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.compat.coerce_string(value)
    │ │ │ -

    Coerce any value to a Unicode string (unicode() in Python 2 and str in Python 3).

    │ │ │ +

    Coerce any value to a Unicode string (unicode() in Python 2 and str in Python 3).

    │ │ │
    │ │ │
    Parameters
    │ │ │

    value – The value to coerce.

    │ │ │
    │ │ │
    Returns
    │ │ │

    The value coerced to a Unicode string.

    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.compat.is_string(value)
    │ │ │ -

    Check if a value is a basestring() (in Python 2) or str (in Python 3) object.

    │ │ │ +

    Check if a value is a basestring() (in Python 2) or str (in Python 3) object.

    │ │ │
    │ │ │
    Parameters
    │ │ │

    value – The value to check.

    │ │ │
    │ │ │
    Returns
    │ │ │ -

    True if the value is a string, False otherwise.

    │ │ │ +

    True if the value is a string, False otherwise.

    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.compat.is_unicode(value)
    │ │ │

    Check if a value is a unicode() (in Python 2) or str (in Python 3) object.

    │ │ │
    │ │ │
    Parameters
    │ │ │

    value – The value to check.

    │ │ │
    │ │ │
    Returns
    │ │ │ -

    True if the value is a Unicode string, False otherwise.

    │ │ │ +

    True if the value is a Unicode string, False otherwise.

    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.compat.on_windows()
    │ │ │

    Check if we’re running on the Microsoft Windows OS.

    │ │ │
    │ │ │
    Returns
    │ │ │ -

    True if running Windows, False otherwise.

    │ │ │ +

    True if running Windows, False otherwise.

    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │

    humanfriendly.decorators

    │ │ │ @@ -2258,15 +2258,15 @@ │ │ │

  • aliases – Each keyword argument defines an alias. The values │ │ │ are expected to be “dotted paths” (strings).

    • │ │ │ │ │ │
    │ │ │
    │ │ │

    The behavior of this function depends on whether the Sphinx documentation │ │ │ generator is active, because the use of DeprecationProxy to shadow the │ │ │ -real module in sys.modules has the unintended side effect of │ │ │ +real module in sys.modules has the unintended side effect of │ │ │ breaking autodoc support for :data: members (module variables).

    │ │ │

    To avoid breaking Sphinx the proxy object is omitted and instead the │ │ │ aliased names are injected into the original module namespace, to make sure │ │ │ that imports can be satisfied when the documentation is being rendered.

    │ │ │

    If you run into cyclic dependencies caused by define_aliases() when │ │ │ running Sphinx, you can try moving the call to define_aliases() to │ │ │ the bottom of the Python module you’re working on.

    │ │ │ @@ -2352,24 +2352,24 @@ │ │ │ humanfriendly.deprecation.is_method(function) │ │ │

    Check if the expected usage of the given function is as an instance method.

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.deprecation.format(text, *args, **kw)
    │ │ │ -

    Format a string using the string formatting operator and/or str.format().

    │ │ │ +

    Format a string using the string formatting operator and/or str.format().

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • text – The text to format (a string).

      • │ │ │

    • args – Any positional arguments are interpolated into the text using │ │ │ the string formatting operator (%). If no positional │ │ │ arguments are given no interpolation is done.

      • │ │ │

    • kw – Any keyword arguments are interpolated into the text using the │ │ │ -str.format() function. If no keyword arguments are given │ │ │ +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).

    │ │ │
    │ │ │ @@ -2414,15 +2414,15 @@ │ │ │ >>> 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 str.format() │ │ │ +

    When you’re doing complex string interpolation the str.format() │ │ │ function results in more readable code, however I frequently find myself │ │ │ adding parentheses to force evaluation order. The 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')
│ │ │ @@ -2457,19 +2457,19 @@
│ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.prompts.prepare_friendly_prompts()
    │ │ │

    Make interactive prompts more user friendly.

    │ │ │

    The prompts presented by raw_input() (in Python 2) and │ │ │ -input() (in Python 3) are not very user friendly by │ │ │ +input() (in Python 3) are not very user friendly by │ │ │ default, for example the cursor keys (←, ↑, → and │ │ │ ↓) and the Home and End keys enter characters instead │ │ │ of performing the action you would expect them to. By simply importing the │ │ │ -readline module these prompts become much friendlier (as mentioned │ │ │ +readline module these prompts become much friendlier (as mentioned │ │ │ in the Python standard library documentation).

    │ │ │

    This function is called by the other functions in this module to enable │ │ │ user friendly prompts.

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ @@ -2496,15 +2496,15 @@ │ │ │ humanfriendly.prompts.prompt_for_choice(choices, default=None, padding=True)
    │ │ │

    Prompt the user to select a choice from a group of options.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • choices – A sequence of strings with available options.

      • │ │ │

    • default – The default choice if the user simply presses Enter │ │ │ -(expected to be a string, defaults to None).

      • │ │ │ +(expected to be a string, defaults to None).

      │ │ │

    • padding – Refer to the documentation of │ │ │ prompt_for_input().

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    The string corresponding to the user’s choice.

    │ │ │
    │ │ │ @@ -2556,37 +2556,37 @@ │ │ │
    │ │ │ humanfriendly.prompts.prompt_for_confirmation(question, default=None, padding=True)
    │ │ │

    Prompt the user for confirmation.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • question – The text that explains what the user is confirming (a string).

      • │ │ │ -

    • default – The default value (a boolean) or None.

      • │ │ │ +

    • default – The default value (a boolean) or None.

      • │ │ │

    • padding – Refer to the documentation of prompt_for_input().

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

      │ │ │ -

    • If the user enters ‘yes’ or ‘y’ then True is returned.

      • │ │ │ -

    • If the user enters ‘no’ or ‘n’ then False is returned.

      • │ │ │ +

    • If the user enters ‘yes’ or ‘y’ then True is returned.

      • │ │ │ +

    • If the user enters ‘no’ or ‘n’ then False is returned.

      • │ │ │

    • If the user doesn’t enter any text or standard input is not │ │ │ connected to a terminal (which makes it impossible to prompt │ │ │ the user) the value of the keyword argument default is │ │ │ -returned (if that value is not None).

      • │ │ │ +returned (if that value is not None).

      │ │ │
    │ │ │

    │ │ │
    │ │ │
    Raises
    │ │ │
    │ │ │
    │ │ │
    │ │ │ -

    When default is False and the user doesn’t enter any text an │ │ │ +

    When default is False and the user doesn’t enter any text an │ │ │ error message is printed and the prompt is repeated:

    │ │ │ 
    >>> prompt_for_confirmation("Are you sure?")
│ │ │  
│ │ │   Are you sure? [y/n]
│ │ │  
│ │ │   Error: Please enter 'yes' or 'no' (there's no default choice).
│ │ │  
│ │ │ @@ -2614,15 +2614,15 @@
│ │ │  
      
│ │ │  
    • question – An explanation of what is expected from the user (a string).
      • 
│ │ │  
    • default – The return value if the user doesn’t enter any text or
│ │ │  standard input is not connected to a terminal (which
│ │ │  makes it impossible to prompt the user).
      • 
│ │ │  
    • padding – Render empty lines before and after the prompt to make it
│ │ │  stand out from the surrounding text? (a boolean, defaults
│ │ │ -to True)
      • 
│ │ │ +to True)
      
│ │ │  
    • strip – Strip leading/trailing whitespace from the user’s reply?
      • 
│ │ │  
    
│ │ │  
    
│ │ │  
    Returns
    
│ │ │  
    The text entered by the user (a string) or the value of the
│ │ │  default argument.
    
│ │ │  
    
│ │ │ @@ -2630,15 +2630,15 @@
│ │ │  
      
│ │ │  
    • KeyboardInterrupt when the program is
│ │ │  interrupted while the prompt is active, for example
│ │ │  because the user presses Control-C.
      • 
│ │ │  
    • EOFError when reading from standard input
│ │ │  fails, for example because the user presses Control-D or
│ │ │  because the standard input stream is redirected (only if
│ │ │ -default is None).
      • 
│ │ │ +default is None).
      
│ │ │  
    
│ │ │  
    
│ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ @@ -2666,15 +2666,15 @@ │ │ │ humanfriendly.prompts.ansi_strip(text, readline_hints=True)
    │ │ │

    Strip ANSI escape sequences from the given string.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • text – The text from which ANSI escape sequences should be removed (a │ │ │ string).

      • │ │ │ -

    • readline_hints – If True then readline_strip() is │ │ │ +

    • readline_hints – If True then readline_strip() is │ │ │ used to remove readline hints from the string.

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    The text without ANSI escape sequences (a string).

    │ │ │
    │ │ │
    │ │ │ @@ -2711,16 +2711,16 @@ │ │ │ humanfriendly.prompts.concatenate(items, conjunction='and', serial_comma=False) │ │ │

    Concatenate a list of items in a human friendly way.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • items – A sequence of strings.

      • │ │ │

    • conjunction – The word to use before the last item (a string, defaults to “and”).

      • │ │ │ -

    • serial_comma – True to use a serial comma, False otherwise │ │ │ -(defaults to False).

      • │ │ │ +

    • serial_comma – True to use a serial comma, False otherwise │ │ │ +(defaults to False).

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    A single string.

    │ │ │
    │ │ │
    │ │ │ 
    >>> from humanfriendly.text import concatenate
│ │ │ @@ -2733,37 +2733,37 @@
│ │ │  
    
│ │ │  
    
│ │ │  humanfriendly.prompts.connected_to_terminal(stream=None)
    
│ │ │  
    Check if a stream is connected to a terminal.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
    stream – The stream to check (a file-like object,
│ │ │ -defaults to sys.stdout).
    
│ │ │ +defaults to sys.stdout).
    
│ │ │  
    
│ │ │  
    Returns
    
│ │ │ -
    True if the stream is connected to a terminal,
│ │ │ -False otherwise.
    
│ │ │ +
    True if the stream is connected to a terminal,
│ │ │ +False otherwise.
    
│ │ │  
    
│ │ │  
    
│ │ │  
    See also terminal_supports_colors().
    
│ │ │  
    
│ │ │  
│ │ │  
    
│ │ │  
    
│ │ │  humanfriendly.prompts.format(text, *args, **kw)
    
│ │ │ -
    Format a string using the string formatting operator and/or str.format().
    
│ │ │ +
    Format a string using the string formatting operator and/or str.format().
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
      
│ │ │  
    • text – The text to format (a string).
      • 
│ │ │  
    • args – Any positional arguments are interpolated into the text using
│ │ │  the string formatting operator (%). If no positional
│ │ │  arguments are given no interpolation is done.
      • 
│ │ │  
    • kw – Any keyword arguments are interpolated into the text using the
│ │ │ -str.format() function. If no keyword arguments are given
│ │ │ +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).
    
│ │ │  
    
│ │ │ @@ -2808,15 +2808,15 @@
│ │ │  >>> 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 str.format() │ │ │ +

    When you’re doing complex string interpolation the str.format() │ │ │ function results in more readable code, however I frequently find myself │ │ │ adding parentheses to force evaluation order. The 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')
│ │ │ @@ -2833,36 +2833,36 @@
│ │ │  
    
│ │ │  
    
│ │ │  humanfriendly.prompts.terminal_supports_colors(stream=None)
    
│ │ │  
    Check if a stream is connected to a terminal that supports ANSI escape sequences.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
    stream – The stream to check (a file-like object,
│ │ │ -defaults to sys.stdout).
    
│ │ │ +defaults to sys.stdout).
    
│ │ │  
    
│ │ │  
    Returns
    
│ │ │ -
    True if the terminal supports ANSI escape sequences,
│ │ │ -False otherwise.
    
│ │ │ +
    True if the terminal supports ANSI escape sequences,
│ │ │ +False otherwise.
    
│ │ │  
    
│ │ │  
    
│ │ │  
    This function was originally inspired by the implementation of
│ │ │  django.core.management.color.supports_color()
│ │ │  but has since evolved significantly.
    
│ │ │  
    
│ │ │  
│ │ │  
    
│ │ │  
    
│ │ │  humanfriendly.prompts.warning(text, *args, **kw)
    
│ │ │  
    Show a warning message on the terminal.
    
│ │ │  
    For details about argument handling please refer to
│ │ │  format().
    
│ │ │  
    Renders the message using format() and writes
│ │ │ -the resulting string (followed by a newline) to sys.stderr using
│ │ │ +the resulting string (followed by a newline) to sys.stderr using
│ │ │  auto_encode().
    
│ │ │ -
    If sys.stderr is connected to a terminal that supports colors,
│ │ │ +
    If sys.stderr is connected to a terminal that supports colors,
│ │ │  ansi_wrap() is used to color the message in a red font (to make
│ │ │  the warning stand out from surrounding text).
    
│ │ │  
    
│ │ │  
│ │ │
    │ │ │
    │ │ │

    humanfriendly.sphinx

    │ │ │ @@ -3089,15 +3089,15 @@ │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.sphinx.dedent(text, *args, **kw)
    │ │ │

    Dedent a string (remove common leading whitespace from all lines).

    │ │ │

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

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • text – The text to dedent (a string).

      • │ │ │

    • args – Any positional arguments are interpolated using format().

      • │ │ │ @@ -3115,24 +3115,24 @@ │ │ │ for data file and code generation tasks (where newlines and indentation are │ │ │ very significant).

      │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.sphinx.format(text, *args, **kw)
    │ │ │ -

    Format a string using the string formatting operator and/or str.format().

    │ │ │ +

    Format a string using the string formatting operator and/or str.format().

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • text – The text to format (a string).

      • │ │ │

    • args – Any positional arguments are interpolated into the text using │ │ │ the string formatting operator (%). If no positional │ │ │ arguments are given no interpolation is done.

      • │ │ │

    • kw – Any keyword arguments are interpolated into the text using the │ │ │ -str.format() function. If no keyword arguments are given │ │ │ +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).

    │ │ │
    │ │ │ @@ -3177,15 +3177,15 @@ │ │ │ >>> 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 str.format() │ │ │ +

    When you’re doing complex string interpolation the str.format() │ │ │ function results in more readable code, however I frequently find myself │ │ │ adding parentheses to force evaluation order. The 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')
│ │ │ @@ -3263,15 +3263,15 @@
│ │ │  
    
│ │ │  
    
│ │ │  humanfriendly.tables.format_pretty_table(data, column_names=None, horizontal_bar='-', vertical_bar='|')
    
│ │ │  
    Render a table using characters like dashes and vertical bars to emulate borders.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
      
│ │ │ -
    • data – An iterable (e.g. a tuple() or list)
│ │ │ +
    • data – An iterable (e.g. a tuple() or list)
│ │ │  containing the rows of the table, where each row is an
│ │ │  iterable containing the columns of the table (strings).
      • 
│ │ │  
    • column_names – An iterable of column names (strings).
      • 
│ │ │  
    • horizontal_bar – The character used to represent a horizontal bar (a
│ │ │  string).
      • 
│ │ │  
    • vertical_bar – The character used to represent a vertical bar (a
│ │ │  string).
      • 
│ │ │ @@ -3322,15 +3322,15 @@
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.tables.format_robust_table(data, column_names)
      
│ │ │  
      Render tabular data with one column per line (allowing columns with line breaks).
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
        
│ │ │ -
      • data – An iterable (e.g. a tuple() or list)
│ │ │ +
      • data – An iterable (e.g. a tuple() or list)
│ │ │  containing the rows of the table, where each row is an
│ │ │  iterable containing the columns of the table (strings).
        • 
│ │ │  
      • column_names – An iterable of column names (strings).
        • 
│ │ │  
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │  
      The rendered table (a string).
      
│ │ │ @@ -3377,15 +3377,15 @@
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.tables.format_rst_table(data, column_names=None)
      
│ │ │  
      Render a table in reStructuredText format.
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
        
│ │ │ -
      • data – An iterable (e.g. a tuple() or list)
│ │ │ +
      • data – An iterable (e.g. a tuple() or list)
│ │ │  containing the rows of the table, where each row is an
│ │ │  iterable containing the columns of the table (strings).
        • 
│ │ │  
      • column_names – An iterable of column names (strings).
        • 
│ │ │  
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │  
      The rendered table (a string).
      
│ │ │ @@ -3418,15 +3418,15 @@
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.tables.format_smart_table(data, column_names)
      
│ │ │  
      Render tabular data using the most appropriate representation.
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
        
│ │ │ -
      • data – An iterable (e.g. a tuple() or list)
│ │ │ +
      • data – An iterable (e.g. a tuple() or list)
│ │ │  containing the rows of the table, where each row is an
│ │ │  iterable containing the columns of the table (strings).
        • 
│ │ │  
      • column_names – An iterable of column names (strings).
        • 
│ │ │  
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │  
      The rendered table (a string).
      
│ │ │ @@ -3451,15 +3451,15 @@
│ │ │  humanfriendly.tables.ansi_strip(text, readline_hints=True)
│ │ │  
      Strip ANSI escape sequences from the given string.
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
        
│ │ │  
      • text – The text from which ANSI escape sequences should be removed (a
│ │ │  string).
        • 
│ │ │ -
      • readline_hints – If True then readline_strip() is
│ │ │ +
      • readline_hints – If True then readline_strip() is
│ │ │  used to remove readline hints from the string.
        • 
│ │ │  
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │  
      The text without ANSI escape sequences (a string).
      
│ │ │  
      
│ │ │  
      
│ │ │ @@ -3507,15 +3507,15 @@
│ │ │  
      
│ │ │  
      
│ │ │  
      
│ │ │  
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.tables.coerce_string(value)
      
│ │ │ -
      Coerce any value to a Unicode string (unicode() in Python 2 and str in Python 3).
      
│ │ │ +
      Coerce any value to a Unicode string (unicode() in Python 2 and str in Python 3).
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
      value – The value to coerce.
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │  
      The value coerced to a Unicode string.
      
│ │ │  
      
│ │ │ @@ -3541,34 +3541,34 @@
│ │ │  
      
│ │ │  
      Note
      
│ │ │  
      The find_terminal_size() function performs the steps
│ │ │  above every time it is called, the result is not cached. This is
│ │ │  because the size of a virtual terminal can change at any time and
│ │ │  the result of find_terminal_size() should be correct.
      
│ │ │  
      Pre-emptive snarky comment: It’s possible to cache the result
│ │ │ -of this function and use signal.SIGWINCH to
│ │ │ +of this function and use signal.SIGWINCH to
│ │ │  refresh the cached values!
      
│ │ │  
      Response: As a library I don’t consider it the role of the
│ │ │  humanfriendly.terminal module to install a process wide
│ │ │  signal handler …
      
│ │ │  
      
│ │ │  
      
│ │ │  
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.tables.terminal_supports_colors(stream=None)
      
│ │ │  
      Check if a stream is connected to a terminal that supports ANSI escape sequences.
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
      stream – The stream to check (a file-like object,
│ │ │ -defaults to sys.stdout).
      
│ │ │ +defaults to sys.stdout).
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │ -
      True if the terminal supports ANSI escape sequences,
│ │ │ -False otherwise.
      
│ │ │ +
      True if the terminal supports ANSI escape sequences,
│ │ │ +False otherwise.
      
│ │ │  
      
│ │ │  
      
│ │ │  
      This function was originally inspired by the implementation of
│ │ │  django.core.management.color.supports_color()
│ │ │  but has since evolved significantly.
      
│ │ │  
      
│ │ │  
│ │ │ @@ -3706,15 +3706,15 @@
│ │ │  humanfriendly.terminal.ansi_strip(text, readline_hints=True)
│ │ │  
      Strip ANSI escape sequences from the given string.
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
        
│ │ │  
      • text – The text from which ANSI escape sequences should be removed (a
│ │ │  string).
        • 
│ │ │ -
      • readline_hints – If True then readline_strip() is
│ │ │ +
      • readline_hints – If True then readline_strip() is
│ │ │  used to remove readline hints from the string.
        • 
│ │ │  
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │  
      The text without ANSI escape sequences (a string).
      
│ │ │  
      
│ │ │  
      
│ │ │ @@ -3731,27 +3731,27 @@
│ │ │  
        
│ │ │  
      • The name of a color (one of the strings ‘black’, ‘red’,
│ │ │  ‘green’, ‘yellow’, ‘blue’, ‘magenta’, ‘cyan’ or ‘white’).
        • 
│ │ │  
      • An integer that refers to the 256 color mode palette.
        • 
│ │ │  
      • A tuple or list with three integers representing an RGB
│ │ │  (red, green, blue) value.
        • 
│ │ │  
      
│ │ │ -
      The value None (the default) means no escape
│ │ │ +
      The value None (the default) means no escape
│ │ │  sequence to switch color will be emitted.
      
│ │ │  
      
│ │ │  
    • background – The background color (see the description
│ │ │  of the color argument).
      • 
│ │ │  
    • bright – Use high intensity colors instead of default colors
│ │ │ -(a boolean, defaults to False).
      • 
│ │ │ -
    • readline_hints – If True then readline_wrap() is
│ │ │ +(a boolean, defaults to False).
      • 
│ │ │ +
    • readline_hints – If True then readline_wrap() is
│ │ │  applied to the generated ANSI escape sequences (the
│ │ │ -default is False).
      • 
│ │ │ +default is False).
      
│ │ │  
    • kw – Any additional keyword arguments are expected to match a key
│ │ │  in the ANSI_TEXT_STYLES dictionary. If the argument’s
│ │ │ -value evaluates to True the respective style will be
│ │ │ +value evaluates to True the respective style will be
│ │ │  enabled.
      • 
│ │ │  
    
│ │ │  
    
│ │ │  
    Returns
    
│ │ │  
    The ANSI escape sequences to enable the requested text styles or
│ │ │  an empty string if no styles were requested.
    
│ │ │  
    
│ │ │ @@ -3829,15 +3829,15 @@
│ │ │  
    
│ │ │  humanfriendly.terminal.auto_encode(stream, text, *args, **kw)
    
│ │ │  
    Reliably write Unicode strings to the terminal.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
      
│ │ │  
    • stream – The file-like object to write to (a value like
│ │ │ -sys.stdout or sys.stderr).
      • 
│ │ │ +sys.stdout or sys.stderr).
      
│ │ │  
    • text – The text to write to the stream (a string).
      • 
│ │ │  
    • args – Refer to format().
      • 
│ │ │  
    • kw – Refer to format().
      • 
│ │ │  
    
│ │ │  
    
│ │ │  
    
│ │ │  
    Renders the text using format() and writes it
│ │ │ @@ -3862,24 +3862,24 @@
│ │ │  
    
│ │ │  
    
│ │ │  
    This function emulates the effect of backspace (0x08), carriage return
│ │ │  (0x0D) and line feed (0x0A) characters and the ANSI ‘erase line’ escape
│ │ │  sequence on interactive terminals. It’s intended to clean up command output
│ │ │  that was originally meant to be rendered on an interactive terminal and
│ │ │  that has been captured using e.g. the script program 3 or the
│ │ │ -pty module 4.
    
│ │ │ +pty module 4.
    
│ │ │  
    
│ │ │  
    3
    
│ │ │  
    My coloredlogs package supports the coloredlogs --to-html
│ │ │  command which uses script to fool a subprocess into thinking
│ │ │  that it’s connected to an interactive terminal (in order to get it
│ │ │  to emit ANSI escape sequences).
    
│ │ │  
    
│ │ │  
    4
    
│ │ │ -
    My capturer package uses the pty module to fool the current
│ │ │ +
    My capturer package uses the pty module to fool the current
│ │ │  process and subprocesses into thinking they are connected to an
│ │ │  interactive terminal (in order to get them to emit ANSI escape
│ │ │  sequences).
    
│ │ │  
    
│ │ │  
    
│ │ │  
    Some caveats about the use of this function:
    
│ │ │  
      
│ │ │ @@ -3899,38 +3899,38 @@
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.terminal.connected_to_terminal(stream=None)
      
│ │ │  
      Check if a stream is connected to a terminal.
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
      stream – The stream to check (a file-like object,
│ │ │ -defaults to sys.stdout).
      
│ │ │ +defaults to sys.stdout).
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │ -
      True if the stream is connected to a terminal,
│ │ │ -False otherwise.
      
│ │ │ +
      True if the stream is connected to a terminal,
│ │ │ +False otherwise.
      
│ │ │  
      
│ │ │  
      
│ │ │  
      See also terminal_supports_colors().
      
│ │ │  
      
│ │ │  
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.terminal.enable_ansi_support()
      
│ │ │  
      Try to enable support for ANSI escape sequences (required on Windows).
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │ -
      True if ANSI is supported, False otherwise.
      
│ │ │ +
      True if ANSI is supported, False otherwise.
      
│ │ │  
      
│ │ │  
      
│ │ │  
      This functions checks for the following supported configurations, in the
│ │ │  given order:
      
│ │ │  
        
│ │ │  
      1. On Windows, if have_windows_native_ansi_support() confirms
│ │ │ -native support for ANSI escape sequences ctypes will be used to
│ │ │ +native support for ANSI escape sequences ctypes will be used to
│ │ │  enable this support.
        2. 
│ │ │  
      2. On Windows, if the environment variable $ANSICON is set nothing is
│ │ │  done because it is assumed that support for ANSI escape sequences has
│ │ │  already been enabled via ansicon.
        3. 
│ │ │  
      3. On Windows, an attempt is made to import and initialize the Python
│ │ │  package colorama instead (of course for this to work
│ │ │  colorama has to be installed).
        4. 
│ │ │ @@ -3966,26 +3966,26 @@
│ │ │  
        
│ │ │  
        Note
        
│ │ │  
        The find_terminal_size() function performs the steps
│ │ │  above every time it is called, the result is not cached. This is
│ │ │  because the size of a virtual terminal can change at any time and
│ │ │  the result of find_terminal_size() should be correct.
        
│ │ │  
        Pre-emptive snarky comment: It’s possible to cache the result
│ │ │ -of this function and use signal.SIGWINCH to
│ │ │ +of this function and use signal.SIGWINCH to
│ │ │  refresh the cached values!
        
│ │ │  
        Response: As a library I don’t consider it the role of the
│ │ │  humanfriendly.terminal module to install a process wide
│ │ │  signal handler …
        
│ │ │  
        
│ │ │  
      
│ │ │  
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.terminal.find_terminal_size_using_ioctl(stream)
      
│ │ │ -
      Find the terminal size using fcntl.ioctl().
      
│ │ │ +
      Find the terminal size using fcntl.ioctl().
      
│ │ │  
      
│ │ │  
      Parameters
      
│ │ │  
      stream – A stream connected to the terminal (a file object with a
│ │ │  fileno attribute).
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │  
      A tuple of two integers with the line and column count.
      
│ │ │ @@ -4049,41 +4049,41 @@
│ │ │  
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.terminal.have_windows_native_ansi_support()
      
│ │ │  
      Check if we’re running on a Windows 10 release with native support for ANSI escape sequences.
      
│ │ │  
      
│ │ │  
      Returns
      
│ │ │ -
      True if so, False otherwise.
      
│ │ │ +
      True if so, False otherwise.
      
│ │ │  
      
│ │ │  
      
│ │ │  
      The cached() decorator is used as a minor
│ │ │  performance optimization. Semantically this should have zero impact because
│ │ │  the answer doesn’t change in the lifetime of a computer process.
      
│ │ │  
      
│ │ │  
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.terminal.message(text, *args, **kw)
      
│ │ │  
      Print a formatted message to the standard error stream.
      
│ │ │  
      For details about argument handling please refer to
│ │ │  format().
      
│ │ │  
      Renders the message using format() and writes
│ │ │ -the resulting string (followed by a newline) to sys.stderr using
│ │ │ +the resulting string (followed by a newline) to sys.stderr using
│ │ │  auto_encode().
      
│ │ │  
      
│ │ │  
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.terminal.output(text, *args, **kw)
      
│ │ │  
      Print a formatted message to the standard output stream.
      
│ │ │  
      For details about argument handling please refer to
│ │ │  format().
      
│ │ │  
      Renders the message using format() and writes
│ │ │ -the resulting string (followed by a newline) to sys.stdout using
│ │ │ +the resulting string (followed by a newline) to sys.stdout using
│ │ │  auto_encode().
      
│ │ │  
      
│ │ │  
│ │ │  
      
│ │ │  
      
│ │ │  humanfriendly.terminal.readline_strip(expr)
      
│ │ │  
      Remove readline hints from a string.
      
│ │ │ @@ -4121,15 +4121,15 @@
│ │ │  
    • formatted_text – The text to print to the terminal (a string).
      • 
│ │ │  
    • encoding – The name of the text encoding used to encode the formatted
│ │ │  text if the formatted text is a Unicode string (a string,
│ │ │  defaults to DEFAULT_ENCODING).
      • 
│ │ │  
    
│ │ │  
    
│ │ │  
    
│ │ │ -
    When connected_to_terminal() returns True a pager is used
│ │ │ +
    When connected_to_terminal() returns True a pager is used
│ │ │  to show the text on the terminal, otherwise the text is printed directly
│ │ │  without invoking a pager.
    
│ │ │  
    The use of a pager helps to avoid the wall of text effect where the user
│ │ │  has to scroll up to see where the output began (not very user friendly).
    
│ │ │  
    Refer to get_pager_command() for details about the command line
│ │ │  that’s used to invoke the pager.
    
│ │ │
    │ │ │ @@ -4137,19 +4137,19 @@ │ │ │
    │ │ │
    │ │ │ humanfriendly.terminal.terminal_supports_colors(stream=None)
    │ │ │

    Check if a stream is connected to a terminal that supports ANSI escape sequences.

    │ │ │
    │ │ │
    Parameters
    │ │ │

    stream – The stream to check (a file-like object, │ │ │ -defaults to sys.stdout).

    │ │ │ +defaults to sys.stdout).

    │ │ │
    │ │ │
    Returns
    │ │ │ -

    True if the terminal supports ANSI escape sequences, │ │ │ -False otherwise.

    │ │ │ +

    True if the terminal supports ANSI escape sequences, │ │ │ +False otherwise.

    │ │ │
    │ │ │
    │ │ │

    This function was originally inspired by the implementation of │ │ │ django.core.management.color.supports_color() │ │ │ but has since evolved significantly.

    │ │ │
    │ │ │ │ │ │ @@ -4160,31 +4160,31 @@ │ │ │
    │ │ │
    Parameters
    │ │ │

    text – The usage message to print (a string).

    │ │ │
    │ │ │
    │ │ │

    This function does two things:

    │ │ │
      │ │ │ -

    1. If sys.stdout is connected to a terminal (see │ │ │ +

    2. If sys.stdout is connected to a terminal (see │ │ │ connected_to_terminal()) then the usage message is formatted │ │ │ using format_usage().

      3. │ │ │

    3. The usage message is shown using a pager (see show_pager()).

      4. │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.terminal.warning(text, *args, **kw)
    │ │ │

    Show a warning message on the terminal.

    │ │ │

    For details about argument handling please refer to │ │ │ format().

    │ │ │

    Renders the message using format() and writes │ │ │ -the resulting string (followed by a newline) to sys.stderr using │ │ │ +the resulting string (followed by a newline) to sys.stderr using │ │ │ auto_encode().

    │ │ │ -

    If sys.stderr is connected to a terminal that supports colors, │ │ │ +

    If sys.stderr is connected to a terminal that supports colors, │ │ │ ansi_wrap() is used to color the message in a red font (to make │ │ │ the warning stand out from surrounding text).

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.terminal.cached(function)
    │ │ │ @@ -4208,15 +4208,15 @@ │ │ │ function arguments, which is not currently the case.

    │ │ │ │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.terminal.coerce_string(value)
    │ │ │ -

    Coerce any value to a Unicode string (unicode() in Python 2 and str in Python 3).

    │ │ │ +

    Coerce any value to a Unicode string (unicode() in Python 2 and str in Python 3).

    │ │ │
    │ │ │
    Parameters
    │ │ │

    value – The value to coerce.

    │ │ │
    │ │ │
    Returns
    │ │ │

    The value coerced to a Unicode string.

    │ │ │
    │ │ │ @@ -4228,16 +4228,16 @@ │ │ │ humanfriendly.terminal.concatenate(items, conjunction='and', serial_comma=False) │ │ │

    Concatenate a list of items in a human friendly way.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • items – A sequence of strings.

      • │ │ │

    • conjunction – The word to use before the last item (a string, defaults to “and”).

      • │ │ │ -

    • serial_comma – True to use a serial comma, False otherwise │ │ │ -(defaults to False).

      • │ │ │ +

    • serial_comma – True to use a serial comma, False otherwise │ │ │ +(defaults to False).

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    A single string.

    │ │ │
    │ │ │
    │ │ │ 
    >>> from humanfriendly.text import concatenate
│ │ │ @@ -4258,15 +4258,15 @@
│ │ │  
  • aliases – Each keyword argument defines an alias. The values
│ │ │  are expected to be “dotted paths” (strings).
    • 
│ │ │  
│ │ │
    │ │ │
    │ │ │

    The behavior of this function depends on whether the Sphinx documentation │ │ │ generator is active, because the use of DeprecationProxy to shadow the │ │ │ -real module in sys.modules has the unintended side effect of │ │ │ +real module in sys.modules has the unintended side effect of │ │ │ breaking autodoc support for :data: members (module variables).

    │ │ │

    To avoid breaking Sphinx the proxy object is omitted and instead the │ │ │ aliased names are injected into the original module namespace, to make sure │ │ │ that imports can be satisfied when the documentation is being rendered.

    │ │ │

    If you run into cyclic dependencies caused by define_aliases() when │ │ │ running Sphinx, you can try moving the call to define_aliases() to │ │ │ the bottom of the Python module you’re working on.

    │ │ │ @@ -4289,24 +4289,24 @@ │ │ │ format such options as --option=ARG. The text ARG in this example │ │ │ is the meta variable.

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.terminal.format(text, *args, **kw)
    │ │ │ -

    Format a string using the string formatting operator and/or str.format().

    │ │ │ +

    Format a string using the string formatting operator and/or str.format().

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • text – The text to format (a string).

      • │ │ │

    • args – Any positional arguments are interpolated into the text using │ │ │ the string formatting operator (%). If no positional │ │ │ arguments are given no interpolation is done.

      • │ │ │

    • kw – Any keyword arguments are interpolated into the text using the │ │ │ -str.format() function. If no keyword arguments are given │ │ │ +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).

    │ │ │
    │ │ │ @@ -4351,15 +4351,15 @@ │ │ │ >>> 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 str.format() │ │ │ +

    When you’re doing complex string interpolation the str.format() │ │ │ function results in more readable code, however I frequently find myself │ │ │ adding parentheses to force evaluation order. The 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')
│ │ │ @@ -4421,26 +4421,26 @@
│ │ │  humanfriendly.terminal.is_unicode(value)
│ │ │  
    Check if a value is a unicode() (in Python 2) or str (in Python 3) object.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
    value – The value to check.
    
│ │ │  
    
│ │ │  
    Returns
    
│ │ │ -
    True if the value is a Unicode string, False otherwise.
    
│ │ │ +
    True if the value is a Unicode string, False otherwise.
    
│ │ │  
    
│ │ │  
    
│ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.terminal.on_windows()
    │ │ │

    Check if we’re running on the Microsoft Windows OS.

    │ │ │
    │ │ │
    Returns
    │ │ │ -

    True if running Windows, False otherwise.

    │ │ │ +

    True if running Windows, False otherwise.

    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.terminal.which(cmd, mode=1, path=None)
    │ │ │ @@ -4504,15 +4504,15 @@ │ │ │ the uppercase symbols are highlighted in light blue with an underline.

    │ │ │

  • <div>, <p> and <pre> tags are considered block level tags │ │ │ and are wrapped in vertical whitespace to prevent their content from │ │ │ “running into” surrounding text. This may cause runs of multiple empty │ │ │ lines to be emitted. As a workaround the __call__() method │ │ │ will automatically call compact_empty_lines() on the generated │ │ │ output before returning it to the caller. Of course this won’t work │ │ │ -when output is set to something like sys.stdout.

    • │ │ │ +when output is set to something like sys.stdout.

    │ │ │

  • <br> is converted to a single plain text line break.

    • │ │ │ │ │ │

    Implementation notes:

    │ │ │
      │ │ │

    • A list of dictionaries with style information is used as a stack where │ │ │ new styling can be pushed and a pop will restore the previous styling. │ │ │ When new styling is pushed, it is merged with (but overrides) the current │ │ │ @@ -4546,15 +4546,15 @@ │ │ │

    • callback – Optional keyword argument to specify a function that │ │ │ will be called to process text fragments before they │ │ │ are emitted on the output stream. Note that link text │ │ │ and preformatted text fragments are not processed by │ │ │ this callback.

      • │ │ │

    • output – Optional keyword argument to redirect the output to the │ │ │ given file-like object. If this is not given a new │ │ │ -StringIO object is created.

      • │ │ │ +StringIO object is created.

      │ │ │
    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ @@ -4562,15 +4562,15 @@ │ │ │

    Reset the parser, convert some HTML and get the text with ANSI escape sequences.

    │ │ │
    │ │ │
    Parameters
    │ │ │

    data – The HTML to convert to text (a string).

    │ │ │
    │ │ │
    Returns
    │ │ │

    The converted text (only in case output is │ │ │ -a StringIO object).

    │ │ │ +a StringIO object).

    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ property current_style
    │ │ │ @@ -4590,15 +4590,15 @@ │ │ │
    │ │ │
    │ │ │ emit_style(style=None)
    │ │ │

    Emit an ANSI escape sequence for the given or current style to the output stream.

    │ │ │
    │ │ │
    Parameters
    │ │ │

    style – A dictionary with arguments for ansi_style() or │ │ │ -None, in which case the style at the top of the │ │ │ +None, in which case the style at the top of the │ │ │ stack is emitted.

    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ @@ -4677,15 +4677,15 @@ │ │ │ parse_color(value)
    │ │ │

    Convert a CSS color to something that ansi_style() understands.

    │ │ │
    │ │ │
    Parameters
    │ │ │

    value – A string like rgb(1,2,3), #AABBCC or yellow.

    │ │ │
    │ │ │
    Returns
    │ │ │ -

    A color value supported by ansi_style() or None.

    │ │ │ +

    A color value supported by ansi_style() or None.

    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ push_styles(**changes)
    │ │ │ @@ -4726,15 +4726,15 @@ │ │ │ │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ reset()
    │ │ │

    Reset the state of the HTML parser and ANSI converter.

    │ │ │ -

    When output is a StringIO object a new │ │ │ +

    When output is a StringIO object a new │ │ │ instance will be created (and the old one garbage collected).

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ urls_match(a, b)
    │ │ │

    Compare two URLs for equality using normalize_url().

    │ │ │ @@ -4742,15 +4742,15 @@ │ │ │
    Parameters
    │ │ │
      │ │ │

    • a – A string containing a URL.

      • │ │ │

    • b – A string containing a URL.

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │ -

    True if the URLs are the same, False otherwise.

    │ │ │ +

    True if the URLs are the same, False otherwise.

    │ │ │
    │ │ │
    │ │ │

    This method is used by handle_endtag() to omit the URL of a │ │ │ hyperlink (<a href="...">) when the link text is that same URL.

    │ │ │
    │ │ │ │ │ │
    │ │ │ @@ -4786,27 +4786,27 @@ │ │ │ │ │ │ -

    The value None (the default) means no escape │ │ │ +

    The value None (the default) means no escape │ │ │ sequence to switch color will be emitted.

    │ │ │

    │ │ │

  • background – The background color (see the description │ │ │ of the color argument).

    • │ │ │

  • bright – Use high intensity colors instead of default colors │ │ │ -(a boolean, defaults to False).

    • │ │ │ -

  • readline_hints – If True then readline_wrap() is │ │ │ +(a boolean, defaults to False).

    • │ │ │ +

  • readline_hints – If True then readline_wrap() is │ │ │ applied to the generated ANSI escape sequences (the │ │ │ -default is False).

    • │ │ │ +default is False).

    │ │ │

  • kw – Any additional keyword arguments are expected to match a key │ │ │ in the ANSI_TEXT_STYLES dictionary. If the argument’s │ │ │ -value evaluates to True the respective style will be │ │ │ +value evaluates to True the respective style will be │ │ │ enabled.

    • │ │ │ │ │ │ │ │ │
    Returns
    │ │ │

    The ANSI escape sequences to enable the requested text styles or │ │ │ an empty string if no styles were requested.

    │ │ │
    │ │ │ @@ -4931,35 +4931,35 @@ │ │ │ when the spinner ends.

    │ │ │
    │ │ │
    │ │ │ class humanfriendly.terminal.spinners.AutomaticSpinner(label, show_time=True)
    │ │ │

    Show a spinner on the terminal that automatically starts animating.

    │ │ │

    This class shows a spinner on the terminal (just like Spinner │ │ │ does) that automatically starts animating. This class should be used as a │ │ │ -context manager using the with statement. The animation │ │ │ +context manager using the with statement. The animation │ │ │ continues for as long as the context is active.

    │ │ │

    AutomaticSpinner provides an alternative to Spinner │ │ │ for situations where it is not practical for the caller to periodically │ │ │ call step() to advance the animation, e.g. because │ │ │ you’re performing a blocking call and don’t fancy implementing threading or │ │ │ subprocess handling just to provide some user feedback.

    │ │ │ -

    This works using the multiprocessing module by spawning a │ │ │ +

    This works using the multiprocessing module by spawning a │ │ │ subprocess to render the spinner while the main process is busy doing │ │ │ -something more useful. By using the with statement you’re │ │ │ +something more useful. By using the with statement you’re │ │ │ guaranteed that the subprocess is properly terminated at the appropriate │ │ │ time.

    │ │ │
    │ │ │
    │ │ │ __init__(label, show_time=True)
    │ │ │

    Initialize an automatic spinner.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • label – The label for the spinner (a string).

      • │ │ │ -

    • show_time – If this is True (the default) then the spinner │ │ │ +

    • show_time – If this is True (the default) then the spinner │ │ │ shows elapsed time.

      • │ │ │
    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │ @@ -4995,21 +4995,21 @@ │ │ │
    │ │ │
    │ │ │ __init__(**options)
    │ │ │

    Initialize a Spinner object.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │ -

    • label – The label for the spinner (a string or None, defaults to │ │ │ -None).

      • │ │ │ -

    • total – The expected number of steps (an integer or None). If this is │ │ │ +

    • label – The label for the spinner (a string or None, defaults to │ │ │ +None).

      • │ │ │ +

    • total – The expected number of steps (an integer or None). If this is │ │ │ provided the spinner will show a progress percentage.

      • │ │ │

    • stream – The output stream to show the spinner on (a file-like object, │ │ │ -defaults to sys.stderr).

      • │ │ │ -

    • interactive – True to enable rendering of the spinner, False to │ │ │ +defaults to sys.stderr).

      • │ │ │ +

    • interactive – True to enable rendering of the spinner, False to │ │ │ disable (defaults to the result of stream.isatty()).

      • │ │ │

    • timer – A Timer object (optional). If this is given the spinner │ │ │ will show the elapsed time according to the timer.

      • │ │ │

    • interval – The spinner will be updated at most once every this many seconds │ │ │ (a floating point number, defaults to MINIMUM_INTERVAL).

      • │ │ │

    • glyphs – A list of strings with single characters that are drawn in the same │ │ │ place in succession to implement a simple animated effect (defaults │ │ │ @@ -5142,24 +5142,24 @@ │ │ │ │ │ │ │ │ │

    │ │ │ │ │ │ │ │ │
    │ │ │

    humanfriendly.testing

    │ │ │ -

    Utility classes and functions that make it easy to write unittest compatible test suites.

    │ │ │ +

    Utility classes and functions that make it easy to write unittest compatible test suites.

    │ │ │

    Over the years I’ve developed the habit of writing test suites for Python │ │ │ -projects using the unittest module. During those years I’ve come to know │ │ │ +projects using the unittest module. During those years I’ve come to know │ │ │ pytest and in fact I use pytest to run my test suites (due to │ │ │ its much better error reporting) but I’ve yet to publish a test suite that │ │ │ requires pytest. I have several reasons for doing so:

    │ │ │
      │ │ │

    • It’s nice to keep my test suites as simple and accessible as possible and │ │ │ not requiring a specific test runner is part of that attitude.

      • │ │ │ -

    • Whereas unittest is quite explicit, pytest contains a lot of │ │ │ +

    • Whereas unittest is quite explicit, pytest contains a lot of │ │ │ magic, which kind of contradicts the Python mantra “explicit is better than │ │ │ implicit” (IMHO).

      • │ │ │
    │ │ │
    │ │ │
    │ │ │ exception humanfriendly.testing.CallableTimedOut
    │ │ │

    Raised by retry() when the timeout expires.

    │ │ │ @@ -5186,15 +5186,15 @@ │ │ │
    │ │ │ │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ class humanfriendly.testing.CaptureOutput(merged=False, input='', enabled=True)
    │ │ │ -

    Context manager that captures what’s written to sys.stdout and sys.stderr.

    │ │ │ +

    Context manager that captures what’s written to sys.stdout and sys.stderr.

    │ │ │
    │ │ │
    │ │ │ stdin
    │ │ │

    The StringIO object used to feed the standard input stream.

    │ │ │
    │ │ │ │ │ │
    │ │ │ @@ -5212,38 +5212,38 @@ │ │ │
    │ │ │
    │ │ │ __init__(merged=False, input='', enabled=True)
    │ │ │

    Initialize a CaptureOutput object.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │ -

    • merged – True to merge the streams, │ │ │ -False to capture them separately.

      • │ │ │ -

    • input – The data that reads from sys.stdin │ │ │ +

    • merged – True to merge the streams, │ │ │ +False to capture them separately.

      • │ │ │ +

    • input – The data that reads from sys.stdin │ │ │ should return (a string).

      • │ │ │ -

    • enabled – True to enable capturing (the default), │ │ │ -False otherwise. This makes it easy to │ │ │ +

    • enabled – True to enable capturing (the default), │ │ │ +False otherwise. This makes it easy to │ │ │ unconditionally use CaptureOutput in │ │ │ -a with block while preserving the │ │ │ +a with block while preserving the │ │ │ choice to opt out of capturing output.

      • │ │ │
    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ __enter__()
    │ │ │ -

    Start capturing what’s written to sys.stdout and sys.stderr.

    │ │ │ +

    Start capturing what’s written to sys.stdout and sys.stderr.

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ __exit__(exc_type=None, exc_value=None, traceback=None)
    │ │ │ -

    Stop capturing what’s written to sys.stdout and sys.stderr.

    │ │ │ +

    Stop capturing what’s written to sys.stdout and sys.stderr.

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ get_lines()
    │ │ │

    Get the contents of stdout split into separate lines.

    │ │ │
    │ │ │ @@ -5253,15 +5253,15 @@ │ │ │ get_text() │ │ │

    Get the contents of stdout as a Unicode string.

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ getvalue()
    │ │ │ -

    Get the text written to sys.stdout.

    │ │ │ +

    Get the text written to sys.stdout.

    │ │ │
    │ │ │ │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ class humanfriendly.testing.ContextManager
    │ │ │ @@ -5288,16 +5288,16 @@ │ │ │ TemporaryDirectory context managers.

    │ │ │
    │ │ │
    │ │ │ __init__(isolated=False)
    │ │ │

    Initialize a CustomSearchPath object.

    │ │ │
    │ │ │
    Parameters
    │ │ │ -

    isolated – True to clear the original search path, │ │ │ -False to add the temporary directory to the │ │ │ +

    isolated – True to clear the original search path, │ │ │ +False to add the temporary directory to the │ │ │ start of the search path.

    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ @@ -5316,15 +5316,15 @@ │ │ │ __exit__(exc_type=None, exc_value=None, traceback=None)
    │ │ │

    Deactivate the custom $PATH.

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ property current_search_path
    │ │ │ -

    The value of $PATH or os.defpath (a string).

    │ │ │ +

    The value of $PATH or os.defpath (a string).

    │ │ │
    │ │ │ │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ class humanfriendly.testing.MockedProgram(name, returncode=0, script=None)
    │ │ │ @@ -5337,15 +5337,15 @@ │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • name – The name of the program (a string).

      • │ │ │

    • returncode – The return code that the program should emit (a │ │ │ number, defaults to zero).

      • │ │ │

    • script – Shell script code to include in the mocked program (a │ │ │ -string or None). This can be used to mock a │ │ │ +string or None). This can be used to mock a │ │ │ program that is expected to generate specific output.

      • │ │ │
    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │ @@ -5373,15 +5373,15 @@ │ │ │
    │ │ │ │ │ │ │ │ │ │ │ │
    │ │ │
    │ │ │ class humanfriendly.testing.PatchedAttribute(obj, name, value)
    │ │ │ -

    Context manager that temporary replaces an object attribute using setattr().

    │ │ │ +

    Context manager that temporary replaces an object attribute using setattr().

    │ │ │
    │ │ │
    │ │ │ __init__(obj, name, value)
    │ │ │

    Initialize a PatchedAttribute object.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │ @@ -5411,15 +5411,15 @@ │ │ │
    │ │ │ │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ class humanfriendly.testing.PatchedItem(obj, item, value)
    │ │ │ -

    Context manager that temporary replaces an object item using __setitem__().

    │ │ │ +

    Context manager that temporary replaces an object item using __setitem__().

    │ │ │
    │ │ │
    │ │ │ __init__(obj, item, value)
    │ │ │

    Initialize a PatchedItem object.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │ @@ -5449,56 +5449,56 @@ │ │ │
    │ │ │ │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ class humanfriendly.testing.TemporaryDirectory(**options)
    │ │ │ -

    Easy temporary directory creation & cleanup using the with statement.

    │ │ │ +

    Easy temporary directory creation & cleanup using the with statement.

    │ │ │

    Here’s an example of how to use this:

    │ │ │ 
    with TemporaryDirectory() as directory:
│ │ │      # Do something useful here.
│ │ │      assert os.path.isdir(directory)
│ │ │
    │ │ │
    │ │ │
    │ │ │
    │ │ │ __init__(**options)
    │ │ │

    Initialize a TemporaryDirectory object.

    │ │ │
    │ │ │
    Parameters
    │ │ │

    options – Any keyword arguments are passed on to │ │ │ -tempfile.mkdtemp().

    │ │ │ +tempfile.mkdtemp().

    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ __enter__()
    │ │ │ -

    Create the temporary directory using tempfile.mkdtemp().

    │ │ │ +

    Create the temporary directory using tempfile.mkdtemp().

    │ │ │
    │ │ │
    Returns
    │ │ │

    The pathname of the directory (a string).

    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ __exit__(exc_type=None, exc_value=None, traceback=None)
    │ │ │ -

    Cleanup the temporary directory using shutil.rmtree().

    │ │ │ +

    Cleanup the temporary directory using shutil.rmtree().

    │ │ │
    │ │ │ │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ class humanfriendly.testing.TestCase(*args, **kw)
    │ │ │ -

    Subclass of unittest.TestCase with automatic logging and other miscellaneous features.

    │ │ │ +

    Subclass of unittest.TestCase with automatic logging and other miscellaneous features.

    │ │ │
    │ │ │
    │ │ │ __init__(*args, **kw)
    │ │ │

    Initialize a TestCase object.

    │ │ │

    Any positional and/or keyword arguments are passed on to the │ │ │ initializer of the superclass.

    │ │ │
    │ │ │ @@ -5509,41 +5509,41 @@ │ │ │

    Automatically configure logging to the terminal.

    │ │ │
    │ │ │
    Parameters
    │ │ │

    log_level – Refer to configure_logging().

    │ │ │
    │ │ │
    │ │ │

    The setUp() method is automatically called by │ │ │ -unittest.TestCase before each test method starts. │ │ │ +unittest.TestCase before each test method starts. │ │ │ It does two things:

    │ │ │
      │ │ │

    • Logging to the terminal is configured using │ │ │ configure_logging().

      • │ │ │

    • Before the test method starts a newline is emitted, to separate the │ │ │ name of the test method (which will be printed to the terminal by │ │ │ -unittest or pytest) from the first line of logging │ │ │ +unittest or pytest) from the first line of logging │ │ │ output that the test method is likely going to generate.

      • │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.testing.configure_logging(log_level=logging.DEBUG)
    │ │ │

    Automatically configure logging to the terminal.

    │ │ │
    │ │ │
    Parameters
    │ │ │

    log_level – The log verbosity (a number, defaults │ │ │ -to logging.DEBUG).

    │ │ │ +to logging.DEBUG).

    │ │ │
    │ │ │
    │ │ │

    When coloredlogs is installed coloredlogs.install() will be │ │ │ used to configure logging to the terminal. When this fails with an │ │ │ -ImportError then logging.basicConfig() is used │ │ │ +ImportError then logging.basicConfig() is used │ │ │ as a fall back.

    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.testing.make_dirs(pathname)
    │ │ │

    Create missing directories.

    │ │ │ @@ -5558,28 +5558,28 @@ │ │ │
    │ │ │ humanfriendly.testing.retry(func, timeout=60, exc_type=AssertionError)
    │ │ │

    Retry a function until assertions no longer fail.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • func – A callable. When the callable returns │ │ │ -False it will also be retried.

      • │ │ │ +False it will also be retried.

      │ │ │

    • timeout – The number of seconds after which to abort (a number, │ │ │ defaults to 60).

      • │ │ │

    • exc_type – The type of exceptions to retry (defaults │ │ │ to AssertionError).

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    The value returned by func.

    │ │ │
    │ │ │
    Raises
    │ │ │

    Once the timeout has expired retry() will raise the │ │ │ previously retried assertion error. When func keeps returning │ │ │ -False until timeout expires CallableTimedOut │ │ │ +False until timeout expires CallableTimedOut │ │ │ will be raised.

    │ │ │
    │ │ │
    │ │ │

    This function sleeps between retries to avoid claiming CPU cycles we don’t │ │ │ need. It starts by sleeping for 0.1 second but adjusts this to one second │ │ │ as the number of retries grows.

    │ │ │
    │ │ │ @@ -5590,26 +5590,26 @@ │ │ │

    Test a command line entry point.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • entry_point – The function that implements the command line interface │ │ │ (a callable).

      • │ │ │

    • arguments – Any positional arguments (strings) become the command │ │ │ -line arguments (sys.argv items 1-N).

      • │ │ │ +line arguments (sys.argv items 1-N).

      │ │ │

    • options –

      The following keyword arguments are supported:

      │ │ │
      │ │ │
      capture

      Whether to use CaptureOutput. Defaults │ │ │ -to True but can be disabled by passing │ │ │ -False instead.

      │ │ │ +to True but can be disabled by passing │ │ │ +False instead.

      │ │ │
      │ │ │
      input

      Refer to CaptureOutput.

      │ │ │
      │ │ │
      merged

      Refer to CaptureOutput.

      │ │ │
      │ │ │ -
      program_name

      Used to set sys.argv item 0.

      │ │ │ +
      program_name

      Used to set sys.argv item 0.

      │ │ │
      │ │ │
      │ │ │

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    A tuple with two values:

    │ │ │ @@ -5621,19 +5621,19 @@ │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.testing.skip_on_raise(*exc_types)
    │ │ │ -

    Decorate a test function to translation specific exception types to unittest.SkipTest.

    │ │ │ +

    Decorate a test function to translation specific exception types to unittest.SkipTest.

    │ │ │
    │ │ │
    Parameters
    │ │ │

    exc_types – One or more positional arguments give the exception │ │ │ -types to be translated to unittest.SkipTest.

    │ │ │ +types to be translated to unittest.SkipTest.

    │ │ │
    │ │ │
    Returns
    │ │ │

    A decorator function specialized to exc_types.

    │ │ │
    │ │ │
    │ │ │
    │ │ │ │ │ │ @@ -5657,15 +5657,15 @@ │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • length – The length of the string to be generated (a number or a │ │ │ tuple with two numbers). If this is a tuple then a random │ │ │ number between the two numbers given in the tuple is used.

      • │ │ │

    • characters – The characters to be used (a string, defaults │ │ │ -to string.ascii_letters).

      • │ │ │ +to string.ascii_letters).

      │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    A random string.

    │ │ │
    │ │ │
    │ │ │

    The random_string() function is very useful in test suites; by the │ │ │ @@ -5738,16 +5738,16 @@ │ │ │ humanfriendly.text.concatenate(items, conjunction='and', serial_comma=False) │ │ │

    Concatenate a list of items in a human friendly way.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • items – A sequence of strings.

      • │ │ │

    • conjunction – The word to use before the last item (a string, defaults to “and”).

      • │ │ │ -

    • serial_comma – True to use a serial comma, False otherwise │ │ │ -(defaults to False).

      • │ │ │ +

    • serial_comma – True to use a serial comma, False otherwise │ │ │ +(defaults to False).

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    A single string.

    │ │ │
    │ │ │
    │ │ │ 
    >>> from humanfriendly.text import concatenate
│ │ │ @@ -5758,15 +5758,15 @@
│ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.text.dedent(text, *args, **kw)
    │ │ │

    Dedent a string (remove common leading whitespace from all lines).

    │ │ │

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

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • text – The text to dedent (a string).

      • │ │ │

    • args – Any positional arguments are interpolated using format().

      • │ │ │ @@ -5784,24 +5784,24 @@ │ │ │ for data file and code generation tasks (where newlines and indentation are │ │ │ very significant).

      │ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.text.format(text, *args, **kw)
    │ │ │ -

    Format a string using the string formatting operator and/or str.format().

    │ │ │ +

    Format a string using the string formatting operator and/or str.format().

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • text – The text to format (a string).

      • │ │ │

    • args – Any positional arguments are interpolated into the text using │ │ │ the string formatting operator (%). If no positional │ │ │ arguments are given no interpolation is done.

      • │ │ │

    • kw – Any keyword arguments are interpolated into the text using the │ │ │ -str.format() function. If no keyword arguments are given │ │ │ +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).

    │ │ │
    │ │ │ @@ -5846,15 +5846,15 @@ │ │ │ >>> 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 str.format() │ │ │ +

    When you’re doing complex string interpolation the str.format() │ │ │ function results in more readable code, however I frequently find myself │ │ │ adding parentheses to force evaluation order. The 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')
│ │ │ @@ -5895,16 +5895,16 @@
│ │ │  humanfriendly.text.is_empty_line(text)
│ │ │  
    Check if a text is empty or contains only whitespace.
    
│ │ │  
    
│ │ │  
    Parameters
    
│ │ │  
    text – The text to check for “emptiness” (a string).
    
│ │ │  
    
│ │ │  
    Returns
    
│ │ │ -
    True if the text is empty or contains only whitespace,
│ │ │ -False otherwise.
    
│ │ │ +
    True if the text is empty or contains only whitespace,
│ │ │ +False otherwise.
    
│ │ │  
    
│ │ │  
    
│ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.text.join_lines(text)
    │ │ │ @@ -5929,15 +5929,15 @@ │ │ │ humanfriendly.text.pluralize(count, singular, plural=None) │ │ │

    Combine a count with the singular or plural form of a word.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • count – The count (a number).

      • │ │ │

    • singular – The singular form of the word (a string).

      • │ │ │ -

    • plural – The plural form of the word (a string or None).

      • │ │ │ +

    • plural – The plural form of the word (a string or None).

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    The count and singular or plural word concatenated (a string).

    │ │ │
    │ │ │
    │ │ │

    See pluralize_raw() for the logic underneath pluralize().

    │ │ │ @@ -5948,15 +5948,15 @@ │ │ │ humanfriendly.text.pluralize_raw(count, singular, plural=None) │ │ │

    Select the singular or plural form of a word based on a count.

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • count – The count (a number).

      • │ │ │

    • singular – The singular form of the word (a string).

      • │ │ │ -

    • plural – The plural form of the word (a string or None).

      • │ │ │ +

    • plural – The plural form of the word (a string or None).

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    The singular or plural form of the word (a string).

    │ │ │
    │ │ │
    │ │ │

    When the given count is exactly 1.0 the singular form of the word is │ │ │ @@ -5974,15 +5974,15 @@ │ │ │

    │ │ │
    Parameters
    │ │ │
      │ │ │

    • length – The length of the string to be generated (a number or a │ │ │ tuple with two numbers). If this is a tuple then a random │ │ │ number between the two numbers given in the tuple is used.

      • │ │ │

    • characters – The characters to be used (a string, defaults │ │ │ -to string.ascii_letters).

      • │ │ │ +to string.ascii_letters).

      │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    A random string.

    │ │ │
    │ │ │
    │ │ │

    The random_string() function is very useful in test suites; by the │ │ │ @@ -6001,15 +6001,15 @@ │ │ │

  • 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 str.split() │ │ │ +

    Here’s the default behavior of Python’s built in str.split() │ │ │ function:

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

    In contrast here’s the default behavior of the split() function:

    │ │ │ 
    >>> from humanfriendly.text import split
│ │ │ @@ -6270,23 +6270,23 @@
│ │ │
    │ │ │ │ │ │
    │ │ │
    │ │ │ humanfriendly.usage.dedent(text, *args, **kw)
    │ │ │

    Dedent a string (remove common leading whitespace from all lines).

    │ │ │

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

    │ │ │ +format().

    │ │ │
    │ │ │
    Parameters
    │ │ │
      │ │ │

    • text – The text to dedent (a string).

      • │ │ │ -

    • args – Any positional arguments are interpolated using format().

      • │ │ │ -

    • kw – Any keyword arguments are interpolated using format().

      • │ │ │ +

    • args – Any positional arguments are interpolated using format().

      • │ │ │ +

    • kw – Any keyword arguments are interpolated using format().

      • │ │ │
    │ │ │
    │ │ │
    Returns
    │ │ │

    The dedented text (a string).

    │ │ │
    │ │ │
    │ │ │

    The compact() function’s documentation contains an example of how I │ │ ├── ./usr/share/doc/python-humanfriendly-doc/html/changelog.html.gz │ │ │ ├── changelog.html │ │ │ │ @@ -229,15 +229,15 @@ │ │ │ │ │ │ │ │ │ │ │ │

    │ │ │ │

    Release 8.0 (2020-03-02)

    │ │ │ │

    This release is backwards incompatible in several ways, see the notes below.

    │ │ │ │

    Enhancements:

    │ │ │ │
      │ │ │ │ -

    • Adopt functools.wraps() to make decorator functions more robust.

      • │ │ │ │ +

    • Adopt functools.wraps() to make decorator functions more robust.

      • │ │ │ │

    • Make the Spinner class more │ │ │ │ customizable. The interval at which spinners are updated and the characters │ │ │ │ used to draw the animation of spinners can now be customized by callers. │ │ │ │ This was triggered by executor issue #2.

      │ │ │ │
      │ │ │ │

      Note

      │ │ │ │

      The text cursor hiding behavior of spinners has been removed │ │ │ │ @@ -329,15 +329,15 @@ │ │ │ │ into the generated documentation because imported classes and their members │ │ │ │ were being included in the documentation, this is now also fixed.

      • │ │ │ │

    • Finally I decided to start using sphinx-build -nW to complain loudly when │ │ │ │ even just one broken reference is found. This should encourage the discipline │ │ │ │ to never introduce broken references again!

      • │ │ │ │
    │ │ │ │

    Tests:

    │ │ │ │ -

    Fixed unittest deprecation warnings in the test suite.

    │ │ │ │ +

    Fixed unittest deprecation warnings in the test suite.

    │ │ │ │
    │ │ │ │
    │ │ │ │

    Release 7.1.1 (2020-02-18)

    │ │ │ │

    Fix Python 3 incompatibility (distutils.spawn).

    │ │ │ │

    Much to my dismay this morning I ran into the following traceback on a Python │ │ │ │ 3.6 installation that is based on native Ubuntu (Debian) packages:

    │ │ │ │ 
    Traceback (most recent call last):
│ │ │ │ @@ -368,15 +368,15 @@
│ │ │ │
    │ │ │ │
    │ │ │ │

    I took this to mean it would be available on all these versions. Furthermore │ │ │ │ the tests on Travis CI passed as well. I think this is because deadsnakes as │ │ │ │ well as Travis CI are closer to upstream (the official Python releases) whereas │ │ │ │ Debian and Ubuntu make significant customizations…

    │ │ │ │

    In any case this new commit should fix the issue by using │ │ │ │ -shutil.which() on Python 3 instead.

    │ │ │ │ +shutil.which() on Python 3 instead.

    │ │ │ │
    │ │ │ │
    │ │ │ │

    Release 7.1 (2020-02-16)

    │ │ │ │

    Enhancements:

    │ │ │ │
    │ │ │ │
    │ │ │ │

    Release 4.12 (2018-04-26)

    │ │ │ │ │ │ │ │
    │ │ │ │
    │ │ │ │

    Release 4.11 (2018-04-26)

    │ │ │ │

    Added this changelog as requested in #23.