humanfriendly

Release 9.2: Sphinx extension metadata

Add humanfriendly.compat.on_macos()

See the changelog update for details.
This fixes #30, #40 and #43.

Release 8.2: Simple case insensitive dictionaries

Release 8.1: Improved output capturing

The work on spinners was prompted by the following:
xolox/python-executor#2

Everything else was me going mad on a refactoring spree 😇

Release 7.3: Support for deprecating positional arguments

Release 7.2: Support for deprecated imports

Release 7.1.1: Restore Debian/Ubuntu Python 3 compatibility (distutil…

Enhancements:

• Enable Windows native support for ANSI escape sequences. This was brought to my attention in coloredlogs issue #71 and coloredlogs pull request #72. My experiences with ANSI escape sequences started out as part of the coloredlogs package but eventually I moved the support for ANSI escape sequences to the humanfriendly package. This explains how it now makes sense to integrate the Windows native ANSI escape sequence support in humanfriendly as well.

Bug fixes:

• Accept pluralized disk size units (#26). I'm not claiming this is a full solution to the problem, far from it. It does lessen the pain a bit (IMHO).

• Make sure the selected pager is available before trying to run it. While testing humanfriendly on Windows 10 I noticed that humanfriendly --help resulted in nothing but a traceback, because less wasn't available. That's not human friendly at all 😕 (even if it is Windows 😈).

After an unplanned but extended hiatus from the development and maintenance of my open source projects I'm now finally starting to pick up some momentum, so I'm trying to make the best of it:

• Merge pull request #24: Fix bug in ~humanfriendly.parse_length() that rounded floats.

• Merge pull request #32: Update hyperlinks in readme.

• Merge pull request #33: Drop support for Python 2.6 and 3.0-3.4

• Merge pull request #35: SVG badge in readme.

• Merge pull request #36: Add support for nanoseconds and microseconds time units

• Fixed ~humanfriendly.tables.format_rst_table() omission from humanfriendly.tables.__all__.

• Start testing on Python 3.8 and 3.9-dev.

• Added a … role for easy linking to packages on the Python Package Index, for details refer to humanfriendly.sphinx.pypi_role().

• Wasted quite a bit of time debugging a MacOS failure on Travis CI caused by a broken pip installation, fixed by using get-pip.py to bootstrap an installation that actually works 😉.

Noteworthy changes:

• Enable ~humanfriendly.testing.MockedProgram to customize the shell script code of mocked programs. This was added to make it easy to mock a program that is expected to generate specific output (I'm planning to use this in the linux-utils test suite).

• Defined __all__ for all public modules that previously lacked "export control" and decided to bump the major version number as a precaution:

  • These changes should not have any impact on backwards compatibility, unless I forgot entries, in which case callers can get ~exceptions.ImportError exceptions...

  • Imports of public modules were previously exported (implicitly) and this pollutes code completion suggestions which in turn can encourage bad practices (not importing things using their "canonical" name).

  • I started developing the humanfriendly package years before I learned about the value of defining __all__ and so some modules lacked a definition until now. I decided that now was as good a time as any to add those definitions 😇.

Miscellaneous changes:

• Simplified the headings in docs/api.rst so that only the module names remain. This was done because Sphinx doesn't support nested links in HTML output and thus generated really weird "Table of Contents" listings.

• Fixed the reStructuredText references in the documentation of ~humanfriendly.prompts.prompt_for_choice(). This function is imported from humanfriendly.prompts to humanfriendly (for backwards compatibility) where it can't use relative references to refer to the other functions in the humanfriendly.prompts module.

• Changed the Makefile to default to Python 3 for development, make sure flake8 is always up-to-date and silence the few targets whose commands were not already silenced.

• Embedded quite a few Python API references into recent changelog entries, just because I could (I ❤️ what hyperlinks can do for the usability of technical documentation, it gives a lot more context).

• Added custom … role for easy linking to Linux manual pages to the humanfriendly.sphinx module.

• Changed rendering of pretty tables to expand tab characters to spaces:

  Until now pretty tables did not take the variable width of tab characters into account which resulted in tables whose "line drawing characters" were visually misaligned. Tabs are now expanded to spaces using str.expandtabs().

• Stop testing on Python 2.6 and drop official support. The world (including Travis CI) has moved on and preserving Python 2.6 compatibility was clearly starting to drag the project down...

I decided to bump the major version number because each of these changes can be considered backwards incompatible in one way or another and version numbers are cheap anyway so there 😛.

• Added humanfriendly.text.generate_slug() function.

• Fixed "invalid escape sequence" DeprecationWarning (pointed out by Python >= 3.6).

• Fought Travis CI (for way too long) in order to restore Python 2.6, 2.7, 3.4, 3.5, 3.6 and 3.7 compatibility in the Travis CI configuration (unrelated to the humanfriendly package itself).

• Add Python 3.7 to versions tested on Travis CI and using tox and document compatibility with Python 3.7.

• Add rudimentary caching decorator for functions:

  Over the years I've used several variations on this function in multiple projects and I'd like to consolidate all of those implementations into a single one that's properly tested and documented.

  Due to the simplicity and lack of external dependencies it seemed kind of fitting to include this in the humanfriendly package, which has become a form of extended standard library for my Python projects 😇.

Yet another ANSI to HTML improvement: Emit an ANSI reset code before emitting ANSI escape sequences that change styles, so that previously activated styles don't inappropriately "leak through" to the text that follows.

More HTML to ANSI improvements:

• Added humanfriendly.text.compact_empty_lines() function.

• Enable optional callback argument to humanfriendly.terminal.html_to_ansi().

• Added a code sample and screenshot to the humanfriendly.terminal.HTMLConverter documentation.

• Emit vertical whitespace for block tags like <div>, <p> and <pre> and post-process the generated output in __call__() to compact empty lines.

• Don't pre-process preformatted text using the user defined text callback.

• Improve robustness against malformed HTML (previously an IndexError would be raised when a closing </a> tag was encountered without a corresponding opening <a> tag).

• Emit an ANSI reset code when humanfriendly.terminal.html.HTMLConverter.close() is called and a style is still active (improves robustness against malformed HTML).

Bug fixes for HTML to ANSI conversion.

HTML entities were being omitted from conversion because I had neglected to define the handle_charref() and handle_entityref() methods (whose definitions are so conveniently given in the documentation of the HTMLParser class 😇).

Added the humanfriendly.terminal.html_to_ansi() function which is a shortcut for the humanfriendly.terminal.HTMLConverter class that's based on html.parser.HTMLParser.

This new functionality converts HTML with simple text formatting tags like <b> for bold, <i> for italic, <u> for underline, <span> for colors, etc. to text with ANSI escape sequences.

I'm still working on that awesome new project (update: see chat-archive_), this functionality was born there but seemed like a useful addition to the humanfriendly package, given the flexibility that this provides 😇.

Support for 24-bit (RGB) terminal colors. Works by accepting a tuple or list with three integers representing an RGB (red, green, blue) color.

Support for italic text rendering on the terminal.

I'm working on an awesome new project (update: see chat-archive) that's almost ready to publish, but then I noticed that I couldn't render italic text on the terminal using the humanfriendly package. I checked and sure enough my terminal supported it just fine, so I didn't see any reason not to fix this now 😇.

It was reported in issue #28 that humanfriendly --demo didn't work on Python 3 due to two unrelated TypeError exceptions. First I added a failing regression test to the test suite (here's the failing build) and then I applied the changes suggested in issue #28, confirming that both issues are indeed fixed because the test now passes (here's the successful build).

• Make humanfriendly.format_timespan() accept datetime.timedelta objects (fixes #27).

• Add license key to setup.py script (pointed out to me in coloredlogs pull request #53).

Added this changelog as requested in #23.

I've held off on having to keep track of changelogs in my open source programming projects until now (2018) because it's yet another piece of bookkeeping that adds overhead to project maintenance versus just writing the damn code and throwing it up on GitHub :-p. However all that time I felt bad for not publishing change logs and I knew that requests would eventually come in and indeed in the past months I've received two requests in #23 and in issue #55 of coloredlogs.

I actually wrote a Python script that uses the git tag and git for-each-ref commands to automatically generate a CHANGELOG.rst "prototype" (requiring manual editing to clean it up) to bootstrap the contents of this document. I'm tempted to publish that now but don't want to get sidetracked even further :-).

Added the humanfriendly.Timer.sleep() method to sleep "no more than" the given number of seconds.

Added the humanfriendly.tables.format_rst_table() function to render RST (reStructuredText) tables.

Added the humanfriendly.coerce_pattern() function. I previously created this for vcs-repo-mgr and now need the same thing in qpass so I'm putting it in humanfriendly :-) because it kind of fits with the other coercion functions.

• Added support for background colors and 256 color mode (related to issue 35 on the coloredlogs issue tracker).

• Added tests for ~humanfriendly.terminal.output(), ~humanfriendly.terminal.message() and ~humanfriendly.terminal.warning().

Fixed issue #21 by implementing support for bright (high intensity) terminal colors.

Fixed issue #16 by merging pull request #17: Extend byte ranges, add RAM output to command line.

In the merge commit I removed the --format-bytes option that #17 added and instead implemented a --binary option which changes --format-size to use binary multiples of bytes (base-2) instead of decimal multiples of bytes (base-10).

• Fixed ImportError exception on Windows due to interactive prompts (fixes #19 by merging #20.).

• Enable MacOS builds on Travis CI and document MacOS compatibility.

• Change Sphinx documentation theme.

Include the Sphinx documentation in source distributions (same rationales as for the similar change made to 'coloredlogs' and 'verboselogs').

Added the ~humanfriendly.testing.make_dirs() and ~humanfriendly.testing.touch() functions.

Don't log duplicate output in ~humanfriendly.testing.run_cli().

Automatically reconfigure logging in ~humanfriendly.testing.run_cli().

Improve ~humanfriendly.testing.run_cli() to always log standard error as well.

Backwards incompatible improvements to ~humanfriendly.testing.run_cli().

I just wasted quite a bit of time debugging a Python 3.6 incompatibility in deb-pkg-tools (see build 251688788) which was obscured by my naive implementation of the run_cli() function. This change is backwards incompatible because run_cli() now intercepts all exceptions whereas previously it would only intercept SystemExit.

Make it easy to mock the $HOME directory.

Enable customizable skipping of tests.

Improved the robustness of the ~humanfriendly.testing.PatchedAttribute and ~humanfriendly.testing.PatchedItem classes.

• Made the retry limit in interactive prompts configurable.

• Refactored the makefile and Travis CI configuration.

Added humanfriendly.testing.TestCase.assertRaises() enhancements.

Bug fix for Python 3 syntax incompatibility.

Promote the command line testing function to the public API.

• Added the humanfriendly.text.random_string() function.

• Added the humanfriendly.testing module with unittest helpers.

• Define humanfriendly.text.__all__.

Added the humanfriendly.terminal.output() function to auto-encode terminal output to avoid encoding errors and applied the use of this function in various places throughout the package.

Improved usage message parsing and rendering.

While working on a new project I noticed that the join_lines() call in render_usage() could corrupt lists as observed here:

https://github.com/xolox/python-rsync-system-backup/blob/ed73787745e706cb6ab76c73acb2480e24d87d7b/README.rst#command-line (check the part after 'Supported locations include:')

To be honest I'm not even sure why I added that join_lines() call to begin with and I can't think of any good reasons to keep it there, so gone it is!

• Added support for min, mins abbreviations for minutes based on #14.

• Added Python 3.6 to supported versions on Travis CI and in documentation.

I've decided to bump the major version number after merging pull request #14 because the humanfriendly.time_units data structure was changed. Even though this module scope variable isn't included in the online documentation, nothing stops users from importing it anyway, so this change is technically backwards incompatible. Besides, version numbers are cheap. In fact, they are infinite! :-)

Make usage() and show_pager() more user friendly by changing how less as a default pager is invoked (with specific options).

Bug fix: Don't hard code conditional dependencies in wheels.

Fix parse_usage() tripping up on commas in option labels.

• Switch to monotonic clock for timers based on #13.

• Change readthedocs.org to readthedocs.io everywhere.

• Improve intersphinx references in documentation.

• Minor improvements to setup script.

• Improve use of timers as context managers by returning the timer object (as originally intended).

• Minor improvements to reStructuredText formatting in various docstrings.

• Fix and add a test for parse_date() choking on Unicode strings.

• Only use "readline hints" in prompts when standard input is a tty.

Added clean_terminal_output() function to sanitize captured terminal output.

Update README.rst based on the changes in 2.0 by merging #12.

Proper support for IEEE 1541 definitions of units (fixes #4, merges #8 and #9).

• Fix and add tests for the timespan formatting issues reported in issues #10 and #11.

• Refactor Makefile, switch to py.test, add wheel support, etc.