API documentation¶

The following API documentation was automatically generated from the source code of humanfriendly 4.18:

A note about backwards compatibility
The humanfriendly module
The humanfriendly.cli module
The humanfriendly.compat module
The humanfriendly.decorators module
The humanfriendly.prompts module
The humanfriendly.sphinx module
The humanfriendly.tables module
The humanfriendly.terminal module
The humanfriendly.testing module
The humanfriendly.text module
The humanfriendly.usage module

A note about backwards compatibility ¶

The humanfriendly package started out as a single humanfriendly module. Eventually this module grew to a size that necessitated splitting up the code into multiple modules (see e.g. tables, terminal, text and usage). Most of the functionality that remains in the humanfriendly module will eventually be moved to submodules as well (as time permits and a logical subdivision of functionality presents itself to me).

While moving functionality around like this my goal is to always preserve backwards compatibility. For example if a function is moved to a submodule an import of that function is added in the main module so that backwards compatibility with previously written import statements is preserved.

If backwards compatibility of documented functionality has to be broken then the major version number will be bumped. So if you’re using the humanfriendly package in your project, make sure to at least pin the major version number in order to avoid unexpected surprises.

The `humanfriendly` module¶

The main module of the humanfriendly package.

class humanfriendly.SizeUnit(divider, symbol, name)¶

__getnewargs__()¶: Return self as a plain tuple. Used by copy and pickle.

static __new__(_cls, divider, symbol, name)¶: Create new instance of SizeUnit(divider, symbol, name)

__repr__()¶: Return a nicely formatted representation string

_asdict()¶: Return a new OrderedDict which maps field names to their values.

classmethod _make(iterable)¶: Make a new SizeUnit object from a sequence or iterable

_replace(**kwds)¶: Return a new SizeUnit object replacing specified fields with new values

property divider¶: Alias for field number 0

property name¶: Alias for field number 2

property symbol¶: Alias for field number 1

class humanfriendly.CombinedUnit(decimal, binary)¶

__getnewargs__()¶: Return self as a plain tuple. Used by copy and pickle.

static __new__(_cls, decimal, binary)¶: Create new instance of CombinedUnit(decimal, binary)

__repr__()¶: Return a nicely formatted representation string

_asdict()¶: Return a new OrderedDict which maps field names to their values.

classmethod _make(iterable)¶: Make a new CombinedUnit object from a sequence or iterable

_replace(**kwds)¶: Return a new CombinedUnit object replacing specified fields with new values

property binary¶: Alias for field number 1

property decimal¶: Alias for field number 0

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.
Other strings raise an exception.

Other Python values are coerced using bool().

Returns

A proper boolean value.

Raises

exceptions.ValueError when the value is a string but cannot be coerced with certainty.

humanfriendly.coerce_pattern(value, flags=0)¶

Coerce strings to compiled regular expressions.

Parameters

value – A string containing a regular expression pattern or a compiled regular expression.
flags – The flags used to compile the pattern (an integer).

Returns

A compiled regular expression.

Raises

ValueError when value isn’t a string and also isn’t a compiled regular expression.

humanfriendly.coerce_seconds(value)¶

Coerce a value to the number of seconds.

Parameters: value – An int, float or datetime.timedelta object.
Returns: An int or float value.

When value is a datetime.timedelta object the total_seconds() method is called. On Python 2.6 this method is not available so it is emulated.

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).

Returns

The corresponding human readable file size (a string).

This function knows how to format sizes in bytes, kilobytes, megabytes, gigabytes, terabytes and petabytes. Some examples:

>>> from humanfriendly import format_size
>>> format_size(0)
'0 bytes'
>>> format_size(1)
'1 byte'
>>> format_size(5)
'5 bytes'
> format_size(1000)
'1 KB'
> format_size(1024, binary=True)
'1 KiB'
>>> format_size(1000 ** 3 * 4)
'4 GB'

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 decimal multiples of bytes (base-10).

Returns

The corresponding size in bytes (an integer).

Raises

InvalidSize when the input can’t be parsed.

This function knows how to parse sizes in bytes, kilobytes, megabytes, gigabytes, terabytes and petabytes. Some examples:

>>> from humanfriendly import parse_size
>>> parse_size('42')
42
>>> parse_size('13b')
13
>>> parse_size('5 bytes')
5
>>> parse_size('1 KB')
1000
>>> parse_size('1 kilobyte')
1000
>>> parse_size('1 KiB')
1024
>>> parse_size('1 KB', binary=True)
1024
>>> parse_size('1.5 GB')
1500000000
>>> parse_size('1.5 GB', binary=True)
1610612736

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.

Returns

The corresponding human readable length (a string).

This function supports ranges from nanometres to kilometres.

Some examples:

>>> from humanfriendly import format_length
>>> format_length(0)
'0 metres'
>>> format_length(1)
'1 metre'
>>> format_length(5)
'5 metres'
>>> format_length(1000)
'1 km'
>>> format_length(0.004)
'4 mm'

humanfriendly.parse_length(length)¶

Parse a human readable length and return the number of metres.

Parameters: length – The human readable length to parse (a string).
Returns: The corresponding length in metres (a float).
Raises: InvalidLength when the input can’t be parsed.

Some examples:

>>> from humanfriendly import parse_length
>>> parse_length('42')
42
>>> parse_length('1 km')
1000
>>> parse_length('5mm')
0.005
>>> parse_length('15.3cm')
0.153

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).
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).

This function is intended to make it easier to recognize the order of size of the number being formatted.

Here’s an example:

>>> from humanfriendly import format_number
>>> print(format_number(6000000))
6,000,000
> print(format_number(6000000000.42))
6,000,000,000.42
> print(format_number(6000000000.42, num_decimals=0))
6,000,000,000

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.

Returns

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

The main purpose of this function is to be used by functions like format_length(), format_size() and format_timespan().

Here are some examples:

>>> from humanfriendly import round_number
>>> round_number(1)
'1'
>>> round_number(math.pi)
'3.14'
>>> round_number(5.001)
'5'

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 instead of being represented as fractional seconds (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.

Raise

See coerce_seconds().

Some examples:

>>> from humanfriendly import format_timespan
>>> format_timespan(0)
'0 seconds'
>>> format_timespan(1)
'1 second'
>>> import math
>>> format_timespan(math.pi)
'3.14 seconds'
>>> hour = 60 * 60
>>> day = hour * 24
>>> week = day * 7
>>> format_timespan(week * 52 + day * 2 + hour * 3)
'1 year, 2 days and 3 hours'

humanfriendly.parse_timespan(timespan)¶

Parse a “human friendly” timespan into the number of seconds.

Parameters: value – A string like 5h (5 hours), 10m (10 minutes) or 42s (42 seconds).
Returns: The number of seconds as a floating point number.
Raises: InvalidTimespan when the input can’t be parsed.

Note that the parse_timespan() function is not meant to be the “mirror image” of the format_timespan() function. Instead it’s meant to allow humans to easily and succinctly specify a timespan with a minimal amount of typing. It’s very useful to accept easy to write time spans as e.g. command line arguments to programs.

The time units (and abbreviations) supported by this function are:

ms, millisecond, milliseconds
s, sec, secs, second, seconds
m, min, mins, minute, minutes
h, hour, hours
d, day, days
w, week, weeks
y, year, years

Some examples:

>>> from humanfriendly import parse_timespan
>>> parse_timespan('42')
42.0
>>> parse_timespan('42s')
42.0
>>> parse_timespan('1m')
60.0
>>> parse_timespan('1h')
3600.0
>>> parse_timespan('1d')
86400.0

humanfriendly.parse_date(datestring)¶

Parse a date/time string into a tuple of integers.

Parameters: datestring – The date/time string to parse.
Returns: A tuple with the numbers (year, month, day, hour, minute, second) (all numbers are integers).
Raises: InvalidDate when the date cannot be parsed.

Supported date/time formats:

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(), 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')
(2013, 6, 17, 0, 0, 0)
>>> parse_date('2013-06-17 02:47:42')
(2013, 6, 17, 2, 47, 42)

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:

>>> 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 parse_date() to calculate a human friendly timespan since a given date:

>>> from humanfriendly import format_timespan, parse_date
>>> from time import mktime, time
>>> unix_time = mktime(parse_date('2013-06-17 02:47:42') + (-1, -1, -1))
>>> seconds_since_then = time() - unix_time
>>> print(format_timespan(seconds_since_then))
1 year, 43 weeks and 1 day

humanfriendly.format_path(pathname)¶

Shorten a pathname to make it more human friendly.

Parameters: pathname – An absolute pathname (a string).
Returns: The pathname with the user’s home directory abbreviated.

Given an absolute pathname, this function abbreviates the user’s home directory to ~/ in order to shorten the pathname without losing information. It is not an error if the pathname is not relative to the current user’s home directory.

Here’s an example of its usage:

>>> from os import environ
>>> from os.path import join
>>> vimrc = join(environ['HOME'], '.vimrc')
>>> vimrc
'/home/peter/.vimrc'
>>> from humanfriendly import format_path
>>> format_path(vimrc)
'~/.vimrc'

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().

Parameters: pathname – A human friendly pathname (a string).
Returns: An absolute pathname (a string).

class humanfriendly.Timer(start_time=None, resumable=False)¶

Easy to use timer to keep track of long during operations.

__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).

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.

Returns: The Timer object.
Raises: ValueError when the timer isn’t resumable.

__exit__(exc_type=None, exc_value=None, traceback=None)¶

Stop counting elapsed time.

Raises: ValueError when the timer isn’t resumable.

sleep(seconds)¶

Easy to use rate limiting of repeating actions.

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 given to it will be the number 0 (negative numbers cause 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 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).

property elapsed_time¶: Get the number of seconds counted so far.

property rounded¶: Human readable timespan rounded to seconds (a string).

__str__()¶: Show the elapsed time since the Timer was created.

class humanfriendly.Spinner(label=None, total=0, stream=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, interactive=None, timer=None, hide_cursor=True)¶

Show a spinner on the terminal as a simple means of feedback to the user.

The Spinner class shows a “spinner” on the terminal to let the user know that something is happening during long running operations that would otherwise be silent (leaving the user to wonder what they’re waiting for). Below are some visual examples that should illustrate the point.

Simple spinners:

Here’s a screen capture that shows the simplest form of spinner:

The following code was used to create the spinner above:

import itertools
import time
from humanfriendly import Spinner

with Spinner(label="Downloading") as spinner:
    for i in itertools.count():
        # Do something useful here.
        time.sleep(0.1)
        # Advance the spinner.
        spinner.step()

Spinners that show elapsed time:

Here’s a spinner that shows the elapsed time since it started:

The following code was used to create the spinner above:

import itertools
import time
from humanfriendly import Spinner, Timer

with Spinner(label="Downloading", timer=Timer()) as spinner:
    for i in itertools.count():
        # Do something useful here.
        time.sleep(0.1)
        # Advance the spinner.
        spinner.step()

Spinners that show progress:

Here’s a spinner that shows a progress percentage:

The following code was used to create the spinner above:

import itertools
import random
import time
from humanfriendly import Spinner, Timer

with Spinner(label="Downloading", total=100) as spinner:
    progress = 0
    while progress < 100:
        # Do something useful here.
        time.sleep(0.1)
        # Advance the spinner.
        spinner.step(progress)
        # Determine the new progress value.
        progress += random.random() * 5

If you want to provide user feedback during a long running operation but it’s not practical to periodically call the step() method consider using AutomaticSpinner instead.

As you may already have noticed in the examples above, Spinner objects can be used as context managers to automatically call clear() when the spinner ends. This helps to make sure that if the text cursor is hidden its visibility is restored before the spinner ends (even if an exception interrupts the spinner).

__init__(label=None, total=0, stream=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>, interactive=None, timer=None, hide_cursor=True)¶

Initialize a spinner.

Parameters

label – The label for the spinner (a string, defaults to None).
total – The expected number of steps (an integer).
stream – The output stream to show the spinner on (defaults to sys.stderr).
interactive – If this is False then the spinner doesn’t write to the output stream at all. It defaults to the return value of stream.isatty().
timer – A Timer object (optional). If this is given the spinner will show the elapsed time according to the timer.
hide_cursor – If True (the default) the text cursor is hidden as long as the spinner is active.

step(progress=0, label=None)¶

Advance the spinner by one step and redraw it.

Parameters

progress – The number of the current step, relative to the total given to the Spinner constructor (an integer, optional). If not provided the spinner will not show progress.
label – The label to use while redrawing (a string, optional). If not provided the label given to the Spinner constructor is used instead.

This method advances the spinner by one step without starting a new line, causing an animated effect which is very simple but much nicer than waiting for a prompt which is completely silent for a long time.

Note

This method uses time based rate limiting to avoid redrawing the spinner too frequently. If you know you’re dealing with code that will call step() at a high frequency, consider using sleep() to avoid creating the equivalent of a busy loop that’s rate limiting the spinner 99% of the time.

sleep()¶

Sleep for a short period before redrawing the spinner.

This method is useful when you know you’re dealing with code that will call step() at a high frequency. It will sleep for the interval with which the spinner is redrawn (less than a second). This avoids creating the equivalent of a busy loop that’s rate limiting the spinner 99% of the time.

This method doesn’t redraw the spinner, you still have to call step() in order to do that.

clear()¶

Clear the spinner.

The next line which is shown on the standard output or error stream after calling this method will overwrite the line that used to show the spinner. Also the visibility of the text cursor is restored.

__enter__()¶

Enable the use of spinners as context managers.

Returns: The Spinner object.

__exit__(exc_type=None, exc_value=None, traceback=None)¶: Clear the spinner when leaving the context.

class humanfriendly.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 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 subprocess to render the spinner while the main process is busy doing 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 shows elapsed time.

__enter__()¶: Enable the use of automatic spinners as context managers.

__exit__(exc_type=None, exc_value=None, traceback=None)¶: Enable the use of automatic spinners as context managers.

exception humanfriendly.InvalidDate¶

Raised when a string cannot be parsed into a date.

For example:

>>> from humanfriendly import parse_date
>>> parse_date('2013-06-XY')
Traceback (most recent call last):
  File "humanfriendly.py", line 206, in parse_date
    raise InvalidDate(format(msg, datestring))
humanfriendly.InvalidDate: Invalid date! (expected 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS' but got: '2013-06-XY')

exception humanfriendly.InvalidSize¶

Raised when a string cannot be parsed into a file size.

For example:

>>> from humanfriendly import parse_size
>>> parse_size('5 Z')
Traceback (most recent call last):
  File "humanfriendly/__init__.py", line 267, in parse_size
    raise InvalidSize(format(msg, size, tokens))
humanfriendly.InvalidSize: Failed to parse size! (input '5 Z' was tokenized as [5, 'Z'])

exception humanfriendly.InvalidLength¶

Raised when a string cannot be parsed into a length.

For example:

>>> from humanfriendly import parse_length
>>> parse_length('5 Z')
Traceback (most recent call last):
  File "humanfriendly/__init__.py", line 267, in parse_length
    raise InvalidLength(format(msg, length, tokens))
humanfriendly.InvalidLength: Failed to parse length! (input '5 Z' was tokenized as [5, 'Z'])

exception humanfriendly.InvalidTimespan¶

Raised when a string cannot be parsed into a timespan.

For example:

>>> from humanfriendly import parse_timespan
>>> parse_timespan('1 age')
Traceback (most recent call last):
  File "humanfriendly/__init__.py", line 419, in parse_timespan
    raise InvalidTimespan(format(msg, timespan, tokens))
humanfriendly.InvalidTimespan: Failed to parse timespan! (input '1 age' was tokenized as [1, 'age'])

The `humanfriendly.cli` module¶

Usage: humanfriendly [OPTIONS]

Human friendly input/output (text formatting) on the command line based on the Python package with the same name.

Supported options:

Option	Description
`-c`, `--run-command`	Execute an external command (given as the positional arguments) and render a spinner and timer while the command is running. The exit status of the command is propagated.
`--format-table`	Read tabular data from standard input (each line is a row and each whitespace separated field is a column), format the data as a table and print the resulting table to standard output. See also the `--delimiter` option.
`-d`, `--delimiter=VALUE`	Change the delimiter used by `--format-table` to `VALUE` (a string). By default all whitespace is treated as a delimiter.
`-l`, `--format-length=LENGTH`	Convert a length count (given as the integer or float `LENGTH`) into a human readable string and print that string to standard output.
`-n`, `--format-number=VALUE`	Format a number (given as the integer or floating point number `VALUE`) with thousands separators and two decimal places (if needed) and print the formatted number to standard output.
`-s`, `--format-size=BYTES`	Convert a byte count (given as the integer `BYTES`) into a human readable string and print that string to standard output.
`-b`, `--binary`	Change the output of `-s`, `--format-size` to use binary multiples of bytes (base-2) instead of the default decimal multiples of bytes (base-10).
`-t`, `--format-timespan=SECONDS`	Convert a number of seconds (given as the floating point number `SECONDS`) into a human readable timespan and print that string to standard output.
`--parse-length=VALUE`	Parse a human readable length (given as the string `VALUE`) and print the number of metres to standard output.
`--parse-size=VALUE`	Parse a human readable data size (given as the string `VALUE`) and print the number of bytes to standard output.
`--demo`	Demonstrate changing the style and color of the terminal font using ANSI escape sequences.
`-h`, `--help`	Show this message and exit.

humanfriendly.cli.main()¶: Command line interface for the humanfriendly program.

humanfriendly.cli.run_command(command_line)¶: Run an external command and show a spinner while the command is running.

humanfriendly.cli.print_formatted_length(value)¶: Print a human readable length.

humanfriendly.cli.print_formatted_number(value)¶: Print large numbers in a human readable format.

humanfriendly.cli.print_formatted_size(value, binary)¶: Print a human readable size.

humanfriendly.cli.print_formatted_table(delimiter)¶: Read tabular data from standard input and print a table.

humanfriendly.cli.print_formatted_timespan(value)¶: Print a human readable timespan.

humanfriendly.cli.print_parsed_length(value)¶: Parse a human readable length and print the number of metres.

humanfriendly.cli.print_parsed_size(value)¶: Parse a human readable data size and print the number of bytes.

humanfriendly.cli.demonstrate_ansi_formatting()¶: Demonstrate the use of ANSI escape sequences.

humanfriendly.cli.demonstrate_256_colors(i, j, group=None)¶: Demonstrate 256 color mode support.

The `humanfriendly.compat` module¶

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 python2:basestring() (in Python 2) or python3:str (in Python 3). See also is_string().

humanfriendly.compat.HTMLParser¶: Alias for python2:HTMLParser.HTMLParser() (in Python 2) or python3:html.parser.HTMLParser() (in Python 3).

humanfriendly.compat.interactive_prompt¶: Alias for python2:raw_input() (in Python 2) or python3:input() (in Python 3).

humanfriendly.compat.StringIO¶: Alias for python2:StringIO.StringIO (in Python 2) or python3:io.StringIO (in Python 3).

humanfriendly.compat.unicode¶: Alias for python2:unicode() (in Python 2) or python3:str (in Python 3). See also coerce_string().

humanfriendly.compat.monotonic¶: Alias for python3:time.monotonic() (in Python 3.3 and higher) or monotonic.monotonic() (a conditional dependency on older Python versions).

humanfriendly.compat.unicode: alias of builtins.str

humanfriendly.compat.unichr()¶: Return a Unicode string of one character with ordinal i; 0 <= i <= 0x10ffff.

humanfriendly.compat.basestring: alias of builtins.str

humanfriendly.compat.interactive_prompt()

Read a string from standard input. The trailing newline is stripped.

The prompt string, if given, is printed to standard output without a trailing newline before reading input.

If the user hits EOF (*nix: Ctrl-D, Windows: Ctrl-Z+Return), raise EOFError. On *nix systems, readline is used if available.

humanfriendly.compat.coerce_string(value)¶

Coerce any value to a Unicode string (python2:unicode() in Python 2 and python3: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 python2:basestring() (in Python 2) or python2:str (in Python 3) object.

Parameters: value – The value to check.
Returns: True if the value is a string, False otherwise.

humanfriendly.compat.is_unicode(value)¶

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

Parameters: value – The value to check.
Returns: True if the value is a Unicode string, False otherwise.

class humanfriendly.compat.HTMLParser(*, convert_charrefs=True)

Find tags and other markup and call handler functions.

Usage:: p = HTMLParser() p.feed(data) … p.close()

Start tags are handled by calling self.handle_starttag() or self.handle_startendtag(); end tags by self.handle_endtag(). The data between tags is passed from the parser to the derived class by calling self.handle_data() with the data as argument (the data may be split up in arbitrary chunks). If convert_charrefs is True the character references are converted automatically to the corresponding Unicode character (and self.handle_data() is no longer split in chunks), otherwise they are passed by calling self.handle_entityref() or self.handle_charref() with the string containing respectively the named or numeric reference as the argument.

__init__(*, convert_charrefs=True)¶

Initialize and reset this instance.

If convert_charrefs is True (the default), all character references are automatically converted to the corresponding Unicode characters.

reset()¶: Reset this instance. Loses all unprocessed data.

feed(data)¶

Feed data to the parser.

Call this as often as you want, with as little or as much text as you want (may include ‘n’).

close()¶: Handle any buffered data.

get_starttag_text()¶: Return full source of start tag: ‘<…>’.

class humanfriendly.compat.StringIO

Text I/O implementation using an in-memory buffer.

The initial_value argument sets the value of object. The newline argument is like the one of TextIOWrapper’s constructor.

close()¶

Close the IO object.

Attempting any further operation after the object is closed will raise a ValueError.

This method has no effect if the file is already closed.

getvalue()¶: Retrieve the entire contents of the object.

newlines¶

Line endings translated so far.

Only line endings translated during reading are considered.

Subclasses should override.

read()¶

Read at most size characters, returned as a string.

If the argument is negative or omitted, read until EOF is reached. Return an empty string at EOF.

readable()¶: Returns True if the IO object can be read.

readline()¶

Read until newline or EOF.

Returns an empty string if EOF is hit immediately.

seek()¶

Change stream position.

Seek to character offset pos relative to position indicated by whence:: 0 Start of stream (the default). pos should be >= 0; 1 Current position - pos must be 0; 2 End of stream - pos must be 0.

Returns the new absolute position.

seekable()¶: Returns True if the IO object can be seeked.

tell()¶: Tell the current file position.

truncate()¶

Truncate size to pos.

The pos argument defaults to the current file position, as returned by tell(). The current file position is unchanged. Returns the new absolute position.

writable()¶: Returns True if the IO object can be written.

write()¶

Write string to file.

Returns the number of characters written, which is always equal to the length of the string.

humanfriendly.compat.monotonic() → float: Monotonic clock, cannot go backward.

The `humanfriendly.decorators` module¶

Simple function decorators to make Python programming easier.

humanfriendly.decorators.RESULTS_ATTRIBUTE = 'cached_results'¶: The name of the property used to cache the return values of functions (a string).

humanfriendly.decorators.cached(function)¶

Rudimentary caching decorator for functions.

Parameters: function – The function whose return value should be cached.
Returns: The decorated function.

The given function will only be called once, the first time the wrapper function is called. The return value is cached by the wrapper function as an attribute of the given function and returned on each subsequent call.

Note

Currently no function arguments are supported because only a single return value can be cached. Accepting any function arguments at all would imply that the cache is parametrized on function arguments, which is not currently the case.

The `humanfriendly.prompts` module¶

Interactive terminal prompts.

The prompts module enables interaction with the user (operator) by asking for confirmation (prompt_for_confirmation()) and asking to choose from a list of options (prompt_for_choice()). It works by rendering interactive prompts on the terminal.

humanfriendly.prompts.MAX_ATTEMPTS = 10¶: The number of times an interactive prompt is shown on invalid input (an integer).

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.
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 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).

Raises

Any exceptions raised by retry_limit().
Any exceptions raised by prompt_for_input().

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?")
 <BLANKLINE>
 Are you sure? [y/n]
 <BLANKLINE>
 Error: Please enter 'yes' or 'no' (there's no default choice).
 <BLANKLINE>
 Are you sure? [y/n]

The same thing happens when the user enters text that isn’t recognized:

>>> prompt_for_confirmation("Are you sure?")
 <BLANKLINE>
 Are you sure? [y/n] about what?
 <BLANKLINE>
 Error: Please enter 'yes' or 'no' (the text 'about what?' is not recognized).
 <BLANKLINE>
 Are you sure? [y/n]

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).
padding – Refer to the documentation of prompt_for_input().

Returns

The string corresponding to the user’s choice.

Raises

ValueError if choices is an empty sequence.
Any exceptions raised by retry_limit().
Any exceptions raised by prompt_for_input().

When no options are given an exception is raised:

>>> prompt_for_choice([])
Traceback (most recent call last):
  File "humanfriendly/prompts.py", line 148, in prompt_for_choice
    raise ValueError("Can't prompt for choice without any options!")
ValueError: Can't prompt for choice without any options!

If a single option is given the user isn’t prompted:

>>> prompt_for_choice(['only one choice'])
'only one choice'

Here’s what the actual prompt looks like by default:

>>> prompt_for_choice(['first option', 'second option'])
 <BLANKLINE>
  1. first option
  2. second option
 <BLANKLINE>
 Enter your choice as a number or unique substring (Control-C aborts): second
 <BLANKLINE>
'second option'

If you don’t like the whitespace (empty lines and indentation):

>>> prompt_for_choice(['first option', 'second option'], padding=False)
 1. first option
 2. second option
Enter your choice as a number or unique substring (Control-C aborts): first
'first option'

humanfriendly.prompts.prompt_for_input(question, default=None, padding=True, strip=True)¶

Prompt the user for input (free form text).

Parameters

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)
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.

Raises

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).

humanfriendly.prompts.prepare_prompt_text(prompt_text, **options)¶

Wrap a text to be rendered as an interactive prompt in ANSI escape sequences.

Parameters

prompt_text – The text to render on the prompt (a string).
options – Any keyword arguments are passed on to ansi_wrap().

Returns

The resulting prompt text (a string).

ANSI escape sequences are only used when the standard output stream is connected to a terminal. When the standard input stream is connected to a terminal any escape sequences are wrapped in “readline hints”.

humanfriendly.prompts.prepare_friendly_prompts()¶

Make interactive prompts more user friendly.

The prompts presented by python2:raw_input() (in Python 2) and python3: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 in the Python standard library documentation).

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

humanfriendly.prompts.retry_limit(limit=10)¶

Allow the user to provide valid input up to limit times.

Parameters: limit – The maximum number of attempts (a number, defaults to MAX_ATTEMPTS).
Returns: A generator of numbers starting from one.
Raises: TooManyInvalidReplies when an interactive prompt receives repeated invalid input (MAX_ATTEMPTS).

This function returns a generator for interactive prompts that want to repeat on invalid input without getting stuck in infinite loops.

exception humanfriendly.prompts.TooManyInvalidReplies¶: Raised by interactive prompts when they’ve received too many invalid inputs.

The `humanfriendly.sphinx` module¶

Customizations for and integration with the Sphinx documentation generator.

The humanfriendly.sphinx module uses the Sphinx extension API to customize the process of generating Sphinx based Python documentation. The most relevant functions to take a look at are setup(), enable_special_methods() and enable_usage_formatting().

humanfriendly.sphinx.setup(app)¶

Enable all of the provided Sphinx customizations.

Parameters: app – The Sphinx application object.

The setup() function makes it easy to enable all of the Sphinx customizations provided by the humanfriendly.sphinx module with the least amount of code. All you need to do is to add the module name to the extensions variable in your conf.py file:

# Sphinx extension module names.
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'humanfriendly.sphinx',
]

When Sphinx sees the humanfriendly.sphinx name it will import the module and call its setup() function.

At the time of writing this just calls enable_special_methods() and enable_usage_formatting(), but of course more functionality may be added at a later stage. If you don’t like that idea you may be better of calling the individual functions from your own setup() function.

humanfriendly.sphinx.enable_special_methods(app)¶

Enable documenting “special methods” using the autodoc extension.

Parameters: app – The Sphinx application object.

This function connects the special_methods_callback() function to autodoc-skip-member events.

humanfriendly.sphinx.special_methods_callback(app, what, name, obj, skip, options)¶

Enable documenting “special methods” using the autodoc extension.

Refer to enable_special_methods() to enable the use of this function (you probably don’t want to call special_methods_callback() directly).

This function implements a callback for autodoc-skip-member events to include documented “special methods” (method names with two leading and two trailing underscores) in your documentation. The result is similar to the use of the special-members flag with one big difference: Special methods are included but other types of members are ignored. This means that attributes like __weakref__ will always be ignored (this was my main annoyance with the special-members flag).

The parameters expected by this function are those defined for Sphinx event callback functions (i.e. I’m not going to document them here :-).

humanfriendly.sphinx.enable_usage_formatting(app)¶

Reformat human friendly usage messages to reStructuredText.

Parameters: app – The Sphinx application object (as given to setup()).

This function connects the usage_message_callback() function to autodoc-process-docstring events.

humanfriendly.sphinx.usage_message_callback(app, what, name, obj, options, lines)¶

Reformat human friendly usage messages to reStructuredText.

Refer to enable_usage_formatting() to enable the use of this function (you probably don’t want to call usage_message_callback() directly).

This function implements a callback for autodoc-process-docstring that reformats module docstrings using render_usage() so that Sphinx doesn’t mangle usage messages that were written to be human readable instead of machine readable. Only module docstrings whose first line starts with USAGE_MARKER are reformatted.

The parameters expected by this function are those defined for Sphinx event callback functions (i.e. I’m not going to document them here :-).

The `humanfriendly.tables` module¶

Functions that render ASCII tables.

Some generic notes about the table formatting functions in this module:

These functions were not written with performance in mind (at all) because they’re intended to format tabular data to be presented on a terminal. If someone were to run into a performance problem using these functions, they’d be printing so much tabular data to the terminal that a human wouldn’t be able to digest the tabular data anyway, so the point is moot :-).
These functions ignore ANSI escape sequences (at least the ones generated by the terminal module) in the calculation of columns widths. On reason for this is that column names are highlighted in color when connected to a terminal. It also means that you can use ANSI escape sequences to highlight certain column’s values if you feel like it (for example to highlight deviations from the norm in an overview of calculated values).

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) 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).

If you want an easy way to render tabular data on a terminal in a human friendly format then this function is for you! It works as follows:

If the input data doesn’t contain any line breaks the function format_pretty_table() is used to render a pretty table. If the resulting table fits in the terminal without wrapping the rendered pretty table is returned.
If the input data does contain line breaks or if a pretty table would wrap (given the width of the terminal) then the function format_robust_table() is used to render a more robust table that can deal with data containing line breaks and long text.

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) 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).

Returns

The rendered table (a string).

Here’s an example:

>>> from humanfriendly.tables import format_pretty_table
>>> column_names = ['Version', 'Uploaded on', 'Downloads']
>>> humanfriendly_releases = [
... ['1.23', '2015-05-25', '218'],
... ['1.23.1', '2015-05-26', '1354'],
... ['1.24', '2015-05-26', '223'],
... ['1.25', '2015-05-26', '4319'],
... ['1.25.1', '2015-06-02', '197'],
... ]
>>> print(format_pretty_table(humanfriendly_releases, column_names))
-------------------------------------
| Version | Uploaded on | Downloads |
-------------------------------------
| 1.23    | 2015-05-25  |       218 |
| 1.23.1  | 2015-05-26  |      1354 |
| 1.24    | 2015-05-26  |       223 |
| 1.25    | 2015-05-26  |      4319 |
| 1.25.1  | 2015-06-02  |       197 |
-------------------------------------

Notes about the resulting table:

If a column contains numeric data (integer and/or floating point numbers) in all rows (ignoring column names of course) then the content of that column is right-aligned, as can be seen in the example above. The idea here is to make it easier to compare the numbers in different columns to each other.
The column names are highlighted in color so they stand out a bit more (see also HIGHLIGHT_COLOR). The following screen shot shows what that looks like (my terminals are always set to white text on a black background):

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) 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).

Here’s an example:

>>> from humanfriendly.tables import format_robust_table
>>> column_names = ['Version', 'Uploaded on', 'Downloads']
>>> humanfriendly_releases = [
... ['1.23', '2015-05-25', '218'],
... ['1.23.1', '2015-05-26', '1354'],
... ['1.24', '2015-05-26', '223'],
... ['1.25', '2015-05-26', '4319'],
... ['1.25.1', '2015-06-02', '197'],
... ]
>>> print(format_robust_table(humanfriendly_releases, column_names))
-----------------------
Version: 1.23
Uploaded on: 2015-05-25
Downloads: 218
-----------------------
Version: 1.23.1
Uploaded on: 2015-05-26
Downloads: 1354
-----------------------
Version: 1.24
Uploaded on: 2015-05-26
Downloads: 223
-----------------------
Version: 1.25
Uploaded on: 2015-05-26
Downloads: 4319
-----------------------
Version: 1.25.1
Uploaded on: 2015-06-02
Downloads: 197
-----------------------

The column names are highlighted in bold font and color so they stand out a bit more (see HIGHLIGHT_COLOR).

The `humanfriendly.terminal` module¶

Interaction with UNIX terminals.

The terminal module makes it easy to interact with UNIX terminals and format text for rendering on UNIX terminals. If the terms used in the documentation of this module don’t make sense to you then please refer to the Wikipedia article on ANSI escape sequences for details about how ANSI escape sequences work.

humanfriendly.terminal.ANSI_CSI = '\x1b['¶: The ANSI “Control Sequence Introducer” (a string).

humanfriendly.terminal.ANSI_SGR = 'm'¶: The ANSI “Select Graphic Rendition” sequence (a string).

humanfriendly.terminal.ANSI_ERASE_LINE = '\x1b[K'¶: The ANSI escape sequence to erase the current line (a string).

humanfriendly.terminal.ANSI_RESET = '\x1b[0m'¶: The ANSI escape sequence to reset styling (a string).

humanfriendly.terminal.ANSI_COLOR_CODES = {'black': 0, 'blue': 4, 'cyan': 6, 'green': 2, 'magenta': 5, 'red': 1, 'white': 7, 'yellow': 3}¶: A dictionary with (name, number) pairs of portable color codes. Used by ansi_style() to generate ANSI escape sequences that change font color.

humanfriendly.terminal.ANSI_TEXT_STYLES = {'bold': 1, 'faint': 2, 'inverse': 7, 'italic': 3, 'strike_through': 9, 'underline': 4}¶: A dictionary with (name, number) pairs of text styles (effects). Used by ansi_style() to generate ANSI escape sequences that change text styles. Only widely supported text styles are included here.

humanfriendly.terminal.CLEAN_OUTPUT_PATTERN = re.compile('(\r|\n|\x08|\x1b\\[K)')¶

A compiled regular expression used to separate significant characters from other text.

This pattern is used by clean_terminal_output() to split terminal output into regular text versus backspace, carriage return and line feed characters and ANSI ‘erase line’ escape sequences.

humanfriendly.terminal.DEFAULT_LINES = 25¶: The default number of lines in a terminal (an integer).

humanfriendly.terminal.DEFAULT_COLUMNS = 80¶: The default number of columns in a terminal (an integer).

humanfriendly.terminal.DEFAULT_ENCODING = 'UTF-8'¶: The output encoding for Unicode strings.

humanfriendly.terminal.HIGHLIGHT_COLOR = 'green'¶: The color used to highlight important tokens in formatted text (e.g. the usage message of the humanfriendly program). If the environment variable $HUMANFRIENDLY_HIGHLIGHT_COLOR is set it determines the value of HIGHLIGHT_COLOR.

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 auto_encode().

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 auto_encode().

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 auto_encode().

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.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).
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 to the given stream. If an UnicodeEncodeError is encountered in doing so, the text is encoded using DEFAULT_ENCODING and the write is retried. The reasoning behind this rather blunt approach is that it’s preferable to get output on the command line in the wrong encoding then to have the Python program blow up with a UnicodeEncodeError exception.

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 used to remove readline hints from the string.

Returns

The text without ANSI escape sequences (a string).

humanfriendly.terminal.ansi_style(**kw)¶

Generate ANSI escape sequences for the given color and/or style(s).

Parameters

color –
The foreground color. Three types of values are supported:
- 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 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 applied to the generated ANSI escape sequences (the 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 enabled.

Returns

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

Raises

ValueError when an invalid color name is given.

Even though only eight named colors are supported, the use of bright=True and faint=True increases the number of available colors to around 24 (it may be slightly lower, for example because faint black is just black).

Support for 8-bit colors

In release 4.7 support for 256 color mode was added. While this significantly increases the available colors it’s not very human friendly in usage because you need to look up color codes in the 256 color mode palette.

You can use the humanfriendly --demo command to get a demonstration of the available colors, see also the screen shot below. Note that the small font size in the screen shot was so that the demonstration of 256 color mode support would fit into a single screen shot without scrolling :-) (I wasn’t feeling very creative).

Support for 24-bit colors

In release 4.14 support for 24-bit colors was added by accepting a tuple or list with three integers representing the RGB (red, green, blue) value of a color. This is not included in the demo because rendering millions of colors was deemed unpractical ;-).

humanfriendly.terminal.ansi_width(text)¶

Calculate the effective width of the given text (ignoring ANSI escape sequences).

Parameters: text – The text whose width should be calculated (a string).
Returns: The width of the text without ANSI escape sequences (an integer).

This function uses ansi_strip() to strip ANSI escape sequences from the given string and returns the length of the resulting string.

humanfriendly.terminal.ansi_wrap(text, **kw)¶

Wrap text in ANSI escape sequences for the given color and/or style(s).

Parameters

text – The text to wrap (a string).
kw – Any keyword arguments are passed to ansi_style().

Returns

The result of this function depends on the keyword arguments:

If ansi_style() generates an ANSI escape sequence based on the keyword arguments, the given text is prefixed with the generated ANSI escape sequence and suffixed with ANSI_RESET.
If ansi_style() returns an empty string then the text given by the caller is returned unchanged.

humanfriendly.terminal.readline_wrap(expr)¶

Wrap an ANSI escape sequence in readline hints.

Parameters: text – The text with the escape sequence to wrap (a string).
Returns: The wrapped text.

humanfriendly.terminal.readline_strip(expr)¶

Remove readline hints from a string.

Parameters: text – The text to strip (a string).
Returns: The stripped text.

humanfriendly.terminal.clean_terminal_output(text)¶

Clean up the terminal output of a command.

Parameters: text – The raw text with special characters (a Unicode string).
Returns: A list of Unicode strings (one for each line).

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 1 or the pty module 2.

1: 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).
2: 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:

Strictly speaking the effect of carriage returns cannot be emulated outside of an actual terminal due to the interaction between overlapping output, terminal widths and line wrapping. The goal of this function is to sanitize noise in terminal output while preserving useful output. Think of it as a useful and pragmatic but possibly lossy conversion.
The algorithm isn’t smart enough to properly handle a pair of ANSI escape sequences that open before a carriage return and close after the last carriage return in a linefeed delimited string; the resulting string will contain only the closing end of the ANSI escape sequence pair. Tracking this kind of complexity requires a state machine and proper parsing.

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).
Returns: True if the stream is connected to a terminal, False otherwise.

The `humanfriendly.testing` module¶

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 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 magic, which kind of contradicts the Python mantra “explicit is better than implicit” (IMHO).

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).

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 as a fall back.

humanfriendly.testing.make_dirs(pathname)¶

Create missing directories.

Parameters: pathname – The pathname of a directory (a string).

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.
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 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.

humanfriendly.testing.run_cli(entry_point, *arguments, **options)¶

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).
options –
The following keyword arguments are supported:

input
Refer to CaptureOutput.

merged
Refer to CaptureOutput.

program_name
Used to set sys.argv item 0.

Returns

A tuple with two values:

The return code (an integer).
The captured output (a string).

humanfriendly.testing.touch(filename)¶

The equivalent of the UNIX touch program in Python.

Parameters: filename – The pathname of the file to touch (a string).

Note that missing directories are automatically created using make_dirs().

exception humanfriendly.testing.CallableTimedOut¶: Raised by retry() when the timeout expires.

class humanfriendly.testing.ContextManager¶

Base class to enable composition of context managers.

__enter__()¶: Enable use as context managers.

__exit__(exc_type=None, exc_value=None, traceback=None)¶: Enable use as context managers.

class humanfriendly.testing.PatchedAttribute(obj, name, value)¶

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

__init__(obj, name, value)¶

Initialize a PatchedAttribute object.

Parameters

obj – The object to patch.
name – An attribute name.
value – The value to set.

__enter__()¶

Replace (patch) the attribute.

Returns: The object whose attribute was patched.

__exit__(exc_type=None, exc_value=None, traceback=None)¶: Restore the attribute to its original value.

class humanfriendly.testing.PatchedItem(obj, item, value)¶

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

__init__(obj, item, value)¶

Initialize a PatchedItem object.

Parameters

obj – The object to patch.
item – The item to patch.
value – The value to set.

__enter__()¶

Replace (patch) the item.

Returns: The object whose item was patched.

__exit__(exc_type=None, exc_value=None, traceback=None)¶: Restore the item to its original value.

class humanfriendly.testing.TemporaryDirectory(**options)¶

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().

__enter__()¶

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().

class humanfriendly.testing.CustomSearchPath(isolated=False)¶

Context manager to temporarily customize $PATH (the executable search path).

This class is a composition of the PatchedItem and 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 start of the search path.

__enter__()¶

Activate the custom $PATH.

Returns: The pathname of the directory that has been added to $PATH (a string).

__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).

class humanfriendly.testing.MockedProgram(name, returncode=0)¶

Context manager to mock the existence of a program (executable).

This class extends the functionality of CustomSearchPath.

__init__(name, returncode=0)¶

Initialize a MockedProgram object.

Parameters

name – The name of the program (a string).
returncode – The return code that the program should emit (a number, defaults to zero).

__enter__()¶

Create the mock program.

Returns: The pathname of the directory that has been added to $PATH (a string).

__exit__(*args, **kw)¶

Ensure that the mock program was run.

Raises: AssertionError when the mock program hasn’t been run.

class humanfriendly.testing.CaptureOutput(merged=False, input='')¶

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

__init__(merged=False, input='')¶

Initialize a CaptureOutput object.

Parameters

merged – True to merge the streams, False to capture them separately.
input – The data that reads from sys.stdin should return (a string).

stdin = None¶: The StringIO object used to feed the standard input stream.

stdout = None¶: The StringIO object used to capture the standard output stream.

stderr = None¶: The StringIO object used to capture the standard error stream.

__enter__()¶: 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.

getvalue()¶: Get the text written to sys.stdout.

class humanfriendly.testing.TestCase(*args, **kw)¶

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

exceptionsToSkip = []¶: A list of exception types that are translated into skipped tests.

__init__(*args, **kw)¶: Wrap test methods using skipTestWrapper().

assertRaises(exception, callable, *args, **kwds)¶

Replacement for unittest.TestCase.assertRaises() that returns the exception.

Refer to the unittest.TestCase.assertRaises() documentation for details on argument handling. The return value is the caught exception.

Warning

This method does not support use as a context manager.

setUp(log_level=logging.DEBUG)¶

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. 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 and/or pytest) from the first line of logging output that the test method is likely going to generate.

shouldSkipTest(exception)¶

Decide whether a test that raised an exception should be skipped.

Parameters: exception – The exception that was raised by the test.
Returns: True to translate the exception into a skipped test, False to propagate the exception as usual.

The shouldSkipTest() method skips exceptions listed in the exceptionsToSkip attribute. This enables subclasses of TestCase to customize the default behavior with a one liner.

skipTest(text, *args, **kw)¶

Enable skipping of tests.

This method was added in humanfriendly 3.3 as a fall back for the unittest.TestCase.skipTest() method that was added in Python 2.7 and 3.1 (because humanfriendly also supports Python 2.6).

Since then humanfriendly has gained a conditional dependency on unittest2 which enables actual skipping of tests (instead of just mocking it) on Python 2.6.

This method now remains for backwards compatibility (and just because it’s a nice shortcut).

skipTestWrapper(test_method, *args, **kw)¶

Wrap test methods to translate exceptions into skipped tests.

Parameters

test_method – The test method to wrap.
args – The positional arguments to the test method.
kw – The keyword arguments to the test method.

Returns

The return value of the test method.

When a TestCase object is initialized, __init__() wraps all of the test_* methods with skipTestWrapper().

When a test method raises an exception, skipTestWrapper() will catch the exception and call shouldSkipTest() to decide whether to translate the exception into a skipped test.

When shouldSkipTest() returns True the exception is swallowed and unittest.SkipTest is raised instead of the original exception.

The `humanfriendly.text` module¶

Simple text manipulation functions.

The text module contains simple functions to manipulate text:

The concatenate() and pluralize() functions make it easy to generate human friendly output.
The format(), compact() and dedent() functions provide a clean and simple to use syntax for composing large text fragments with interpolated variables.
The tokenize() function parses simple user input.

humanfriendly.text.compact(text, *args, **kw)¶

Compact whitespace in a string.

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

Parameters

text – The text to compact (a string).
args – Any positional arguments are interpolated using format().
kw – Any keyword arguments are interpolated using format().

Returns

The compacted text (a string).

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

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

The combination of compact() and Python’s multi line strings allows me to write long text fragments with interpolated variables that are easy to write, easy to read and work well with Python’s whitespace sensitivity.

humanfriendly.text.compact_empty_lines(text)¶

Replace repeating empty lines with a single empty line (similar to cat -s).

Parameters: text – The text in which to compact empty lines (a string).
Returns: The text with empty lines compacted (a string).

humanfriendly.text.concatenate(items)¶

Concatenate a list of items in a human friendly way.

Parameters: items – A sequence of strings.
Returns: A single string.

>>> from humanfriendly.text import concatenate
>>> concatenate(["eggs", "milk", "bread"])
'eggs, milk and bread'

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 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().
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 like to use the compact() and dedent() functions. The main difference is that I use compact() for text that will be presented to the user (where whitespace is not so significant) and dedent() 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().

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 no interpolation is done.

Returns

The text with any positional and/or keyword arguments interpolated (a string).

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

Why format() instead of the string formatting operator?

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

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

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

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

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

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

When you’re doing complex string interpolation the 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')
"silly example (can't think of anything less silly)"
>>> format("{adjective} example" + " " + "(can't think of anything less {adjective})", adjective='silly')
"silly example (can't think of anything less silly)"

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

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.

humanfriendly.text.join_lines(text)¶

Remove “hard wrapping” from the paragraphs in a string.

Parameters: text – The text to reformat (a string).
Returns: The text without hard wrapping (a string).

This function works by removing line breaks when the last character before a line break and the first character after the line break are both non-whitespace characters. This means that common leading indentation will break join_lines() (in that case you can use dedent() before calling join_lines()).

humanfriendly.text.pluralize(count, singular, plural=None)¶

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

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

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).

Returns

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

humanfriendly.text.random_string(length=(25, 100), characters=string.ascii_letters)¶

Generate a random string.

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).

Returns

A random string.

The random_string() function is very useful in test suites; by the time I included it in humanfriendly.text I had already included variants of this function in seven different test suites :-).

humanfriendly.text.split(text, delimiter=', ')¶

Split a comma-separated list of strings.

Parameters

text – The text to split (a string).
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() function:

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

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

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

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

>>> from pprint import pprint
>>> encoded_data = 'debug=green;warning=yellow;error=red;critical=red,bold'
>>> parsed_data = dict((k, split(v, ',')) for k, v in (split(kv, '=') for kv in split(encoded_data, ';')))
>>> pprint(parsed_data)
{'debug': ['green'],
 'warning': ['yellow'],
 'error': ['red'],
 'critical': ['red', 'bold']}

humanfriendly.text.split_paragraphs(text)¶

Split a string into paragraphs (one or more lines delimited by an empty line).

Parameters: text – The text to split into paragraphs (a string).
Returns: A list of strings.

humanfriendly.text.tokenize(text)¶

Tokenize a text into numbers and strings.

Parameters: text – The text to tokenize (a string).
Returns: A list of strings and/or numbers.

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

>>> from humanfriendly.text import tokenize
>>> tokenize('42')
[42]
>>> tokenize('42MB')
[42, 'MB']
>>> tokenize('42.5MB')
[42.5, 'MB']
>>> tokenize('42.5 MB')
[42.5, 'MB']

humanfriendly.text.trim_empty_lines(text)¶

Trim leading and trailing empty lines from the given text.

Parameters: text – The text to trim (a string).
Returns: The trimmed text (a string).

The `humanfriendly.usage` module¶

Parsing and reformatting of usage messages.

The usage module parses and reformats usage messages:

The format_usage() function takes a usage message and inserts ANSI escape sequences that highlight items of special significance like command line options, meta variables, etc. The resulting usage message is (intended to be) easier to read on a terminal.
The render_usage() function takes a usage message and rewrites it to reStructuredText suitable for inclusion in the documentation of a Python package. This provides a DRY solution to keeping a single authoritative definition of the usage message while making it easily available in documentation. As a cherry on the cake it’s not just a pre-formatted dump of the usage message but a nicely formatted reStructuredText fragment.
The remaining functions in this module support the two functions above.

Usage messages in general are free format of course, however the functions in this module assume a certain structure from usage messages in order to successfully parse and reformat them, refer to parse_usage() for details.

humanfriendly.usage.USAGE_MARKER = 'Usage:'¶: The string that starts the first line of a usage message.

humanfriendly.usage.format_usage(usage_text)¶

Highlight special items in a usage message.

Parameters: usage_text – The usage message to process (a string).
Returns: The usage message with special items highlighted.

This function highlights the following special items:

The initial line of the form “Usage: …”
Short and long command line options
Environment variables
Meta variables (see find_meta_variables())

All items are highlighted in the color defined by HIGHLIGHT_COLOR.

humanfriendly.usage.find_meta_variables(usage_text)¶

Find the meta variables in the given usage message.

Parameters: usage_text – The usage message to parse (a string).
Returns: A list of strings with any meta variables found in the usage message.

When a command line option requires an argument, the convention is to format such options as --option=ARG. The text ARG in this example is the meta variable.

humanfriendly.usage.parse_usage(text)¶

Parse a usage message by inferring its structure (and making some assumptions :-).

Parameters

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

Returns

A tuple of two lists:

A list of strings with the paragraphs of the usage message’s “introduction” (the paragraphs before the documentation of the supported command line options).
A list of strings with pairs of command line options and their descriptions: Item zero is a line listing a supported command line option, item one is the description of that command line option, item two is a line listing another supported command line option, etc.

Usage messages in general are free format of course, however parse_usage() assume a certain structure from usage messages in order to successfully parse them:

The usage message starts with a line Usage: ... that shows a symbolic representation of the way the program is to be invoked.
After some free form text a line Supported options: (surrounded by empty lines) precedes the documentation of the supported command line options.
The command line options are documented as follows:
```
-v, --verbose

  Make more noise.
```
So all of the variants of the command line option are shown together on a separate line, followed by one or more paragraphs describing the option.
There are several other minor assumptions, but to be honest I’m not sure if anyone other than me is ever going to use this functionality, so for now I won’t list every intricate detail :-).

If you’re curious anyway, refer to the usage message of the humanfriendly package (defined in the humanfriendly.cli module) and compare it with the usage message you see when you run humanfriendly --help and the generated usage message embedded in the readme.

Feel free to request more detailed documentation if you’re interested in using the humanfriendly.usage module outside of the little ecosystem of Python packages that I have been building over the past years.

humanfriendly.usage.render_usage(text)¶

Reformat a command line program’s usage message to reStructuredText.

Parameters: text – The plain text usage message (a string).
Returns: The usage message rendered to reStructuredText (a string).

humanfriendly.usage.inject_usage(module_name)¶

Use cog to inject a usage message into a reStructuredText file.

Parameters: module_name – The name of the module whose __doc__ attribute is the source of the usage message (a string).

This simple wrapper around render_usage() makes it very easy to inject a reformatted usage message into your documentation using cog. To use it you add a fragment like the following to your *.rst file:

.. [[[cog
.. from humanfriendly.usage import inject_usage
.. inject_usage('humanfriendly.cli')
.. ]]]
.. [[[end]]]

The lines in the fragment above are single line reStructuredText comments that are not copied to the output. Their purpose is to instruct cog where to inject the reformatted usage message. Once you’ve added these lines to your *.rst file, updating the rendered usage message becomes really simple thanks to cog:

$ cog.py -r README.rst

This will inject or replace the rendered usage message in your README.rst file with an up to date copy.

humanfriendly.usage.import_module(name, package=None)¶

Import a module.

The ‘package’ argument is required when performing a relative import. It specifies the package to use as the anchor point from which to resolve the relative import to an absolute import.

API documentation¶

A note about backwards compatibility ¶

The `humanfriendly` module¶

The `humanfriendly.cli` module¶

The `humanfriendly.compat` module¶

The `humanfriendly.decorators` module¶

The `humanfriendly.prompts` module¶

The `humanfriendly.sphinx` module¶

The `humanfriendly.tables` module¶

The `humanfriendly.terminal` module¶

The `humanfriendly.testing` module¶

The `humanfriendly.text` module¶

The `humanfriendly.usage` module¶

Table of Contents

Previous topic

Next topic

This Page

API documentation¶

A note about backwards compatibility¶

The humanfriendly module¶

The humanfriendly.cli module¶

The humanfriendly.compat module¶

The humanfriendly.decorators module¶

The humanfriendly.prompts module¶

The humanfriendly.sphinx module¶

The humanfriendly.tables module¶

The humanfriendly.terminal module¶

The humanfriendly.testing module¶

The humanfriendly.text module¶

The humanfriendly.usage module¶

A note about backwards compatibility ¶

The `humanfriendly` module¶

The `humanfriendly.cli` module¶

The `humanfriendly.compat` module¶

The `humanfriendly.decorators` module¶

The `humanfriendly.prompts` module¶

The `humanfriendly.sphinx` module¶

The `humanfriendly.tables` module¶

The `humanfriendly.terminal` module¶

The `humanfriendly.testing` module¶

The `humanfriendly.text` module¶

The `humanfriendly.usage` module¶