The purpose of this document is to list all of the notable changes to this project. The format was inspired by (but doesn’t strictly adhere to) Keep a Changelog . This project adheres to semantic versioning.
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:
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 ansi_to_html() function which is a shortcut for the 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).
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 Timer.sleep() method to sleep “no more than” the given number of seconds.
Added the format_rst_table() function to render RST (reStructuredText) tables.
Added the 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.
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).
Include the Sphinx documentation in source distributions (same rationales as for the similar change made to ‘coloredlogs’ and ‘verboselogs’).
Added the make_dirs() and touch() functions to the humanfriendly.testing module.
Don’t log duplicate output in run_cli().
Automatically reconfigure logging in run_cli().
Improve 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 PatchedAttribute and PatchedItem classes.
Added TestCase.assertRaises() enhancements.
Bug fix for Python 3 syntax incompatibility.
Promote the command line testing function to the public API.
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!
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.
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).
Minor improvements to usage message reformatting.
Remove an undocumented .strip() call from join_lines().
Why I noticed this: It has the potential to eat significant white space in usage messages that are marked up in reStructuredText syntax.
Why I decided to change it: The behavior isn’t documented and on second thought I wouldn’t expect a function called join_lines() to strip any and all leading/trailing white space.
Improved the usage message parsing algorithm (also added a proper test). Refer to test_parse_usage_tricky() for an example of a usage message that is now parsed correctly but would previously confuse the dumb “parsing” algorithm in parse_usage().
Made usage message parsing a bit more strict. Admittedly this still needs a lot more love to make it more robust but I lack the time to implement this at the moment. Some day soon! :-)
Unbreak conditional importlib dependency after breakage observed here: https://travis-ci.org/xolox/python-humanfriendly/builds/110585766
Added the humanfriendly.sphinx module with automagic usage message reformatting and a bit of code that I’d been copying and pasting between docs/conf.py scripts for years to include magic methods, etc in Sphinx generated documentation.
Bug fix for Python 2.6 compatibility in setup.py script.
Replaced import_module() with a conditional dependency on importlib.
Added proper tests for ANSI escape sequence support.
Added support for custom delimiters in humanfriendly.text.split().
Added the humanfriendly.compat module to group Python 2 / 3 compatibility logic.
Added message() and warning() functions to write informational and warning messages to the terminal (on the standard error stream).
Implemented the feature request in issue #6: Support for milleseconds in timespan parsing/formatting. Technically speaking this breaks backwards compatibility but only by dropping a nasty (not documented) implementation detail. Quoting from the old code:
# All of the first letters of the time units are unique, so
# although this check is not very strict I believe it to be
# sufficient.
That no longer worked with [m]illiseconds versus [m]inutes as was also evident from the feature request / bug report on GitHub.
Implemented and added checks to enforce PEP-8 and PEP-257 compliance.
Added format_length() and parse_length()` functions via pull request #5.
Added the humanfriendly.text.split() function.
Added support for rendering of usage messages to reStructuredText.
Started moving functions to separate modules.
Added the parse_timespan() function.
Extracted the “new” tokenize() function from the existing parse_size() function.
Changed table formatting to right-align table columns with numeric data (and pimped the documentation).
Make table formatting ‘smart’ by having it automatically handle overflow of columns by switching to a different more verbose vertical table layout.
Added the humanfriendly.terminal.usage() function for nice rendering of usage messages on interactive terminals (try humanfriendly --help to see it in action).
Added the humanfriendly.terminal module with support for ANSI escape sequences, detecting interactive terinals, finding the terminal size, etc.
Bug fix for Python 3 compatibility in format_table().
Added format_table() function to format tabular data in simple textual tables.
Added additional string formatting functions compact(), dedent(), format(), is_empty_line() and trim_empty_lines().
Added support for formatting numbers with thousands separators.
Made it possible to use spinners as context managers.
Added a Spinner.sleep() method.
Added support for spinners with an embedded timer.
Added support for rounded timestamps.
Added coerce_boolean() function.
Improved pluralize() by making it handle the simple case of pluralizing by adding ‘s’.
Improved the documentation by adding a few docstring examples via pull request #3.
Improved the test suite by making the timing related tests less sensitive to slow test execution. See https://travis-ci.org/xolox/python-humanfriendly/jobs/28706938 but the same thing can happen anywhere. When looked at from that perspective the fix I’m committing here really isn’t a fix, but I suspect it will be fine :-).
Added support for ‘B’ bytes unit to parse_size() via pull request #2.
Improved the prompt_for_choice() function by clearly presenting the default choice (if any).
Added the prompt_for_choice() function.
Enable Spinner to show progress counter (percentage).
Make Timer objects “resumable”.
Make the Spinner(label=...) argument optional.
Make it possible to override the label for individual steps of spinners.
Automatically rate limit Spinner instances.
Bug fix for concatenate() when given only one item.
Added functions concatenate() and pluralize(), both originally developed in private scripts.
Bug fix: Don’t raise an error in format_path() if $HOME isn’t set.
Added a Spinner class that I originally developed for pip-accel.
Added a Timer class to easily keep track of long running operations.
Fixed various edge cases in format_path(), making it more robust.
Improved the project description in setup.py and added a link to online documentation on PyPI.
Renamed the package from human-friendly to humanfriendly.
Added the parse_date() function.
Added the format_timespan() function.
Started using Sphinx to generate API documentation from docstrings.
Added the format_path() function.
The initial commit of the project, created by gathering functions from various personal scripts that I wrote over the past years.