humanfriendly: Human friendly input/output in Python

Welcome to the documentation of humanfriendly version 10.0! The following sections are available:

User documentation

The readme is the best place to start reading, it’s targeted at all users and documents the command line interface:

• humanfriendly: Human friendly input/output in Python
  • Getting started
  • Command line
  • A note about size units
  • Windows support
  • Contact
  • License

API documentation

The following API documentation is automatically generated from the source code:

• API documentation
  • A note about backwards compatibility
  • humanfriendly
    • format_table
    • compact
    • concatenate
    • dedent
    • format
    • is_empty_line
    • pluralize
    • tokenize
    • trim_empty_lines
    • prompt_for_choice
    • AutomaticSpinner
    • Spinner
    • erase_line_code
    • hide_cursor_code
    • minimum_spinner_interval
    • show_cursor_code
    • CombinedUnit
      • CombinedUnit.__getnewargs__()
      • CombinedUnit.__new__()
      • CombinedUnit.__replace__()
      • CombinedUnit.__repr__()
      • CombinedUnit._asdict()
      • CombinedUnit._make()
      • CombinedUnit._replace()
      • CombinedUnit.binary
      • CombinedUnit.decimal
    • InvalidDate
    • InvalidLength
    • InvalidSize
    • InvalidTimespan
    • SizeUnit
      • SizeUnit.__getnewargs__()
      • SizeUnit.__new__()
      • SizeUnit.__replace__()
      • SizeUnit.__repr__()
      • SizeUnit._asdict()
      • SizeUnit._make()
      • SizeUnit._replace()
      • SizeUnit.divider
      • SizeUnit.name
      • SizeUnit.symbol
    • Timer
      • Timer.__init__()
      • Timer.__enter__()
      • Timer.__exit__()
      • Timer.sleep()
      • Timer.elapsed_time
      • Timer.rounded
      • Timer.__str__()
    • coerce_boolean()
    • coerce_pattern()
    • coerce_seconds()
    • format_length()
    • format_number()
    • format_path()
    • format_size()
    • format_timespan()
    • parse_date()
    • parse_length()
    • parse_path()
    • parse_size()
    • parse_timespan()
    • round_number()
    • compact()
    • concatenate()
    • dedent()
    • define_aliases()
    • format()
    • format_table()
    • is_empty_line()
    • is_string()
    • pluralize()
    • prompt_for_choice()
    • tokenize()
    • trim_empty_lines()
  • humanfriendly.case
    • CaseInsensitiveDict
      • CaseInsensitiveDict.__init__()
      • CaseInsensitiveDict.coerce_key()
      • CaseInsensitiveDict.fromkeys()
      • CaseInsensitiveDict.get()
      • CaseInsensitiveDict.pop()
      • CaseInsensitiveDict.setdefault()
      • CaseInsensitiveDict.update()
      • CaseInsensitiveDict.__contains__()
      • CaseInsensitiveDict.__delitem__()
      • CaseInsensitiveDict.__getitem__()
      • CaseInsensitiveDict.__setitem__()
    • CaseInsensitiveKey
      • CaseInsensitiveKey.__new__()
      • CaseInsensitiveKey.__hash__()
      • CaseInsensitiveKey.__eq__()
  • humanfriendly.cli
    • demonstrate_256_colors()
    • demonstrate_ansi_formatting()
    • main()
    • print_formatted_length()
    • print_formatted_number()
    • print_formatted_size()
    • print_formatted_table()
    • print_formatted_timespan()
    • print_parsed_length()
    • print_parsed_size()
    • run_command()
    • ansi_strip()
    • ansi_wrap()
    • enable_ansi_support()
    • find_terminal_size()
    • format_length()
    • format_number()
    • format_pretty_table()
    • format_size()
    • format_smart_table()
    • format_timespan()
    • output()
    • parse_length()
    • parse_size()
    • quote()
    • usage()
    • warning()
  • humanfriendly.compat
    • basestring
    • HTMLParser
    • interactive_prompt
    • StringIO
    • unicode
    • monotonic
    • coerce_string()
    • is_string()
    • is_unicode()
    • on_macos()
    • on_windows()
  • humanfriendly.decorators
    • RESULTS_ATTRIBUTE
    • cached()
  • humanfriendly.deprecation
    • DeprecationProxy
      • DeprecationProxy.__init__()
      • DeprecationProxy.__getattr__()
      • DeprecationProxy.resolve()
    • define_aliases()
    • deprecated_args()
    • get_aliases()
    • is_method()
    • format()
  • humanfriendly.prompts
    • MAX_ATTEMPTS
    • TooManyInvalidReplies
    • prepare_friendly_prompts()
    • prepare_prompt_text()
    • prompt_for_choice()
    • prompt_for_confirmation()
    • prompt_for_input()
    • retry_limit()
    • ansi_strip()
    • ansi_wrap()
    • concatenate()
    • connected_to_terminal()
    • format()
    • terminal_supports_colors()
    • warning()
  • humanfriendly.sphinx
    • deprecation_note_callback()
    • enable_deprecation_notes()
    • enable_man_role()
    • enable_pypi_role()
    • enable_special_methods()
    • enable_usage_formatting()
    • man_role()
    • pypi_role()
    • setup()
    • special_methods_callback()
    • usage_message_callback()
    • compact()
    • dedent()
    • format()
    • get_aliases()
    • render_usage()
    • update_lines()
  • humanfriendly.tables
    • format_pretty_table()
    • format_robust_table()
    • format_rst_table()
    • format_smart_table()
    • ansi_strip()
    • ansi_width()
    • ansi_wrap()
    • coerce_string()
    • find_terminal_size()
    • terminal_supports_colors()
  • humanfriendly.terminal
    • find_meta_variables
    • format_usage
    • html_to_ansi
    • HTMLConverter
    • ANSI_COLOR_CODES
    • ANSI_CSI
    • ANSI_ERASE_LINE
    • ANSI_HIDE_CURSOR
    • ANSI_RESET
    • ANSI_SGR
    • ANSI_SHOW_CURSOR
    • ANSI_TEXT_STYLES
    • CLEAN_OUTPUT_PATTERN
    • DEFAULT_COLUMNS
    • DEFAULT_ENCODING
    • DEFAULT_LINES
    • HIGHLIGHT_COLOR
    • ansi_strip()
    • ansi_style()
    • ansi_width()
    • ansi_wrap()
    • auto_encode()
    • clean_terminal_output()
    • connected_to_terminal()
    • enable_ansi_support()
    • find_terminal_size()
    • find_terminal_size_using_ioctl()
    • find_terminal_size_using_stty()
    • get_pager_command()
    • have_windows_native_ansi_support()
    • message()
    • output()
    • readline_strip()
    • readline_wrap()
    • show_pager()
    • terminal_supports_colors()
    • usage()
    • warning()
    • cached()
    • coerce_string()
    • concatenate()
    • define_aliases()
    • find_meta_variables()
    • format()
    • format_usage()
    • html_to_ansi()
    • is_unicode()
    • on_windows()
    • which()
  • humanfriendly.terminal.html
    • HTMLConverter
      • HTMLConverter.BLOCK_TAGS
      • HTMLConverter.__init__()
      • HTMLConverter.__call__()
      • HTMLConverter.current_style
      • HTMLConverter.close()
      • HTMLConverter.emit_style()
      • HTMLConverter.handle_charref()
      • HTMLConverter.handle_data()
      • HTMLConverter.handle_endtag()
      • HTMLConverter.handle_entityref()
      • HTMLConverter.handle_starttag()
      • HTMLConverter.normalize_url()
      • HTMLConverter.parse_color()
      • HTMLConverter.push_styles()
      • HTMLConverter.render_url()
      • HTMLConverter.reset()
      • HTMLConverter.urls_match()
    • html_to_ansi()
    • ansi_style()
    • compact_empty_lines()
  • humanfriendly.terminal.spinners
    • AutomaticSpinner
      • AutomaticSpinner.__init__()
      • AutomaticSpinner.__enter__()
      • AutomaticSpinner.__exit__()
    • GLYPHS
    • MINIMUM_INTERVAL
    • Spinner
      • Spinner.__init__()
      • Spinner.step()
      • Spinner.sleep()
      • Spinner.clear()
      • Spinner.__enter__()
      • Spinner.__exit__()
    • deprecated_args()
  • humanfriendly.testing
    • CallableTimedOut
    • CaptureBuffer
      • CaptureBuffer.get_lines()
      • CaptureBuffer.get_text()
    • CaptureOutput
      • CaptureOutput.stdin
      • CaptureOutput.stdout
      • CaptureOutput.stderr
      • CaptureOutput.__init__()
      • CaptureOutput.__enter__()
      • CaptureOutput.__exit__()
      • CaptureOutput.get_lines()
      • CaptureOutput.get_text()
      • CaptureOutput.getvalue()
    • ContextManager
      • ContextManager.__enter__()
      • ContextManager.__exit__()
    • CustomSearchPath
      • CustomSearchPath.__init__()
      • CustomSearchPath.__enter__()
      • CustomSearchPath.__exit__()
      • CustomSearchPath.current_search_path
    • MockedProgram
      • MockedProgram.__init__()
      • MockedProgram.__enter__()
      • MockedProgram.__exit__()
    • PatchedAttribute
      • PatchedAttribute.__init__()
      • PatchedAttribute.__enter__()
      • PatchedAttribute.__exit__()
    • PatchedItem
      • PatchedItem.__init__()
      • PatchedItem.__enter__()
      • PatchedItem.__exit__()
    • TemporaryDirectory
      • TemporaryDirectory.__init__()
      • TemporaryDirectory.__enter__()
      • TemporaryDirectory.__exit__()
    • TestCase
      • TestCase.__init__()
      • TestCase.setUp()
    • configure_logging()
    • make_dirs()
    • retry()
    • run_cli()
    • skip_on_raise()
    • touch()
    • quote()
    • random_string()
  • humanfriendly.text
    • compact()
    • compact_empty_lines()
    • concatenate()
    • dedent()
    • format()
    • generate_slug()
    • is_empty_line()
    • join_lines()
    • pluralize()
    • pluralize_raw()
    • random_string()
    • split()
    • split_paragraphs()
    • tokenize()
    • trim_empty_lines()
  • humanfriendly.usage
    • find_meta_variables()
    • format_usage()
    • import_module()
    • inject_usage()
    • parse_usage()
    • render_usage()
    • USAGE_MARKER
    • dedent()
    • split_paragraphs()
    • trim_empty_lines()

Change log

The change log lists notable changes to the project:

• Changelog
  • Release 10.0 (2021-09-17)
  • Release 9.2 (2021-06-11)
  • Release 9.1 (2020-12-10)
  • Release 9.0 (2020-12-01)
  • Release 8.2 (2020-04-19)
  • Release 8.1 (2020-03-06)
  • Release 8.0 (2020-03-02)
  • Release 7.3 (2020-03-02)
  • Release 7.2 (2020-03-01)
  • Release 7.1.1 (2020-02-18)
  • Release 7.1 (2020-02-16)
  • Release 7.0 (2020-02-16)
  • Release 6.1 (2020-02-10)
  • Release 6.0 (2020-02-09)
  • Release 5.0 (2020-02-06)
  • Release 4.18 (2019-02-21)
  • Release 4.17 (2018-10-20)
  • Release 4.16.1 (2018-07-21)
  • Release 4.16 (2018-07-21)
  • Release 4.15.1 (2018-07-14)
  • Release 4.15 (2018-07-14)
  • Release 4.14 (2018-07-13)
  • Release 4.13 (2018-07-09)
  • Release 4.12.1 (2018-05-10)
  • Release 4.12 (2018-04-26)
  • Release 4.11 (2018-04-26)
  • Release 4.10 (2018-03-31)
  • Release 4.9 (2018-03-28)
  • Release 4.8 (2018-01-20)
  • Release 4.7 (2018-01-14)
  • Release 4.6 (2018-01-04)
  • Release 4.5 (2018-01-04)
  • Release 4.4.2 (2018-01-04)
  • Release 4.4.1 (2017-08-07)
  • Release 4.4 (2017-07-16)
  • Release 4.3 (2017-07-10)
  • Release 4.2 (2017-07-10)
  • Release 4.1 (2017-07-10)
  • Release 4.0 (2017-07-10)
  • Release 3.8 (2017-07-02)
  • Release 3.7 (2017-07-01)
  • Release 3.6.1 (2017-06-24)
  • Release 3.6 (2017-06-24)
  • Release 3.5 (2017-06-24)
  • Release 3.4.1 (2017-06-24)
  • Release 3.4 (2017-06-24)
  • Release 3.3 (2017-06-24)
  • Release 3.2 (2017-05-18)
  • Release 3.1 (2017-05-06)
  • Release 3.0 (2017-05-04)
  • Release 2.4 (2017-02-14)
  • Release 2.3.2 (2017-01-17)
  • Release 2.3.1 (2017-01-17)
  • Release 2.3 (2017-01-16)
  • Release 2.2.1 (2017-01-10)
  • Release 2.2 (2016-11-30)
  • Release 2.1 (2016-10-09)
  • Release 2.0.1 (2016-09-29)
  • Release 2.0 (2016-09-29)
  • Release 1.44.9 (2016-09-28)
  • Release 1.44.8 (2016-09-28)
  • Release 1.44.7 (2016-04-21)
  • Release 1.44.6 (2016-04-21)
  • Release 1.44.5 (2016-03-20)
  • Release 1.44.4 (2016-03-15)
  • Release 1.44.3 (2016-02-20)
  • Release 1.44.2 (2016-02-20)
  • Release 1.44.1 (2016-02-18)
  • Release 1.44 (2016-02-17)
  • Release 1.43.1 (2016-01-19)
  • Release 1.43 (2016-01-19)
  • Release 1.42 (2015-10-23)
  • Release 1.41 (2015-10-22)
  • Release 1.40 (2015-10-22)
  • Release 1.39 (2015-10-22)
  • Release 1.38 (2015-10-22)
  • Release 1.37 (2015-10-22)
  • Release 1.36 (2015-10-21)
  • Release 1.35 (2015-09-10)
  • Release 1.34 (2015-08-06)
  • Release 1.33 (2015-07-27)
  • Release 1.32 (2015-07-19)
  • Release 1.31 (2015-06-28)
  • Release 1.30 (2015-06-28)
  • Release 1.29 (2015-06-24)
  • Release 1.28 (2015-06-24)
  • Release 1.27 (2015-06-03)
  • Release 1.26 (2015-06-02)
  • Release 1.25.1 (2015-06-02)
  • Release 1.25 (2015-05-27)
  • Release 1.24 (2015-05-27)
  • Release 1.23.1 (2015-05-26)
  • Release 1.23 (2015-05-26)
  • Release 1.22 (2015-05-26)
  • Release 1.21 (2015-05-25)
  • Release 1.20 (2015-05-25)
  • Release 1.19 (2015-05-23)
  • Release 1.18 (2015-05-23)
  • Release 1.17 (2015-05-23)
  • Release 1.16 (2015-03-29)
  • Release 1.15 (2015-03-17)
  • Release 1.14 (2014-11-22)
  • Release 1.13 (2014-11-16)
  • Release 1.12 (2014-11-16)
  • Release 1.11 (2014-11-15)
  • Release 1.10 (2014-11-15)
  • Release 1.9.6 (2014-09-14)
  • Release 1.9.5 (2014-06-29)
  • Release 1.9.4 (2014-06-29)
  • Release 1.9.3 (2014-06-29)
  • Release 1.9.2 (2014-06-29)
  • Release 1.9.1 (2014-06-23)
  • Release 1.9 (2014-06-23)
  • Release 1.8.6 (2014-06-08)
  • Release 1.8.5 (2014-06-08)
  • Release 1.8.4 (2014-06-07)
  • Release 1.8.3 (2014-06-07)
  • Release 1.8.2 (2014-06-01)
  • Release 1.8.1 (2014-05-11)
  • Release 1.8 (2014-05-10)
  • Release 1.7.1 (2013-09-22)
  • Release 1.7 (2013-09-22)
  • Release 1.6.1 (2013-09-22)
  • Release 1.6 (2013-08-12)
  • Release 1.5 (2013-07-07)
  • Release 1.4.3 (2013-07-06)
  • Release 1.4.2 (2013-06-27)
  • Release 1.4.1 (2013-06-27)
  • Release 1.4 (2013-06-17)
  • Release 1.3.1 (2013-06-17)
  • Release 1.3 (2013-06-17)
  • Release 1.2 (2013-06-17)
  • Release 1.1 (2013-06-17)
  • Release 1.0 (2013-06-17)