Package: humanfriendly
The functions and classes in thehumanfriendlypackage can be used to make
text interfaces more user friendly. Some example features:Parsing and formatting numbers, file sizes, pathnames and timespans in
simple, human friendly formats.Easy to use timers for long running operations, with human friendly
formatting of the resulting timespans.Prompting the user to select a choice from a list of options by typing the
option’s number or a unique substring of the option.Terminal interaction including text styling (ANSI escape sequences), user
friendly rendering of usage messages and querying the terminal for its
size.Thehumanfriendlypackage is currently tested on Python 2.7, 3.5+ and PyPy
(2.7) on Linux and macOS. While the intention is to support Windows as well,
you may encounter some rough edges.Getting startedCommand lineA note about size unitsWindows supportContactLicenseGetting startedIt’s very simple to start using thehumanfriendlypackage:>>> from humanfriendly import format_size, parse_size
>>> from humanfriendly.prompts import prompt_for_input
>>> user_input = prompt_for_input("Enter a readable file size: ")

  Enter a readable file size: 16G

>>> num_bytes = parse_size(user_input)
>>> print(num_bytes)
16000000000
>>> print("You entered:", format_size(num_bytes))
You entered: 16 GB
>>> print("You entered:", format_size(num_bytes, binary=True))
You entered: 14.9 GiBTo get a demonstration of supported terminal text styles (based onANSI escape sequences) you can run the following command:$ humanfriendly --demoCommand lineUsage:humanfriendly [OPTIONS]Human friendly input/output (text formatting) on the command
line based on the Python package with the same name.Supported options:OptionDescription-c,--run-commandExecute 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-tableRead 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--delimiteroption.-d,--delimiter=VALUEChange the delimiter used by--format-tabletoVALUE(a string). By default
all whitespace is treated as a delimiter.-l,--format-length=LENGTHConvert a length count (given as the integer or floatLENGTH) into a human
readable string and print that string to standard output.-n,--format-number=VALUEFormat a number (given as the integer or floating point numberVALUE) with
thousands separators and two decimal places (if needed) and print the
formatted number to standard output.-s,--format-size=BYTESConvert a byte count (given as the integerBYTES) into a human readable
string and print that string to standard output.-b,--binaryChange the output of-s,--format-sizeto use binary multiples of bytes
(base-2) instead of the default decimal multiples of bytes (base-10).-t,--format-timespan=SECONDSConvert a number of seconds (given as the floating point numberSECONDS)
into a human readable timespan and print that string to standard output.--parse-length=VALUEParse a human readable length (given as the stringVALUE) and print the
number of metres to standard output.--parse-size=VALUEParse a human readable data size (given as the stringVALUE) and print the
number of bytes to standard output.--demoDemonstrate changing the style and color of the terminal font using ANSI
escape sequences.-h,--helpShow this message and exit.A note about size unitsWhen I originally published thehumanfriendlypackage I went with binary
multiples of bytes (powers of two). It was pointed out several times that this
was a poor choice (see issue#4and pull requests#8and#9) and thus
the new default became decimal multiples of bytes (powers of ten):UnitBinary valueDecimal valueKB10241000MB10485761000000GB10737418241000000000TB10995116277761000000000000etcThe option to use binary multiples of bytes remains by passing the keyword
argumentbinary=Trueto theformat_size()andparse_size()functions.Windows supportWindows 10 gained native support for ANSI escape sequences which means commands
likehumanfriendly--demoshould work out of the box (if your system is
up-to-date enough). If this doesn’t work then you can install thecoloramapackage, it will be used automatically once installed.ContactThe latest version ofhumanfriendlyis available onPyPIandGitHub. The
documentation is hosted onRead the Docsand includes achangelog. For bug
reports please create an issue onGitHub. If you have questions, suggestions,
etc. feel free to send me an e-mail atpeter@peterodding.com.LicenseThis software is licensed under theMIT license.© 2021 Peter Odding.