Release notes from sidetrack

Release 2.0.1

2022-01-11T00:52:54Z

This version adds a backward compatibility function logr that is identical to log.

Release 2.0.0

2021-07-12T19:59:45Z

This introduces backwards-incompatible changes to the API, and adds one new function.

In recognition that modern Python code more often uses f-strings, the function logr is now named log, and what was previously log is now called logf. Users who called the log function with single strings will not notice any difference; users who called it with more than one argument (a string and format arguments) will get an error; and users who called logr will also get an error, about an undefined function. The new set of log functions is more logically organized:

log takes a single argument, a string. It does not apply format to the string.
loglist is like log, except it accepts multiple strings. It prints them one line at time.
logf takes a single string as the first argument and optionally multiple arguments after that. It passes the optional arguments to format.

An advantage of the new scheme is that it is more obvious when a message string will be passed to format. Previously, if a string contained a character that had special meaning to format (particularly {) was passed to log, it would result in an unexpected error. Now, the requirement to use the variant logf hopefully makes it more obvious that the arguments are being treated specially.

Release 1.4.0

2021-03-04T16:27:12Z

This version adds a new option to set_debug(...): the flag show_package, which will cause Sidetrack to prefix messages with the name of the Python package containing the source file from where the log function was called. This flag is useful if you use Sidetrack in multiple packages, or import packages that also use Sidetrack.

Release 1.3.0

2020-11-25T23:10:15Z

This version changes the logging level used by Sidetrack. The level is now set to the value of logging.DEBUG + 1 (that is, the numeric value 11). This solves a problem caused by Python packages that turn off DEBUG-level logging at import time: previously, if such a package was imported after Sidetrack was loaded, it would end up disabling Sidetrack as a side-effect. This should no longer happen. (Plus, we can now legitimately say that Sidetrack goes to 11.)

Release 1.2.0

2020-09-24T20:20:08Z

This version brings no changes to the API, but does remove a dependency on setuptools, and brings internal changes that solve problems in using Sidetrack inside binaries produced by PyInstaller. The internal changes remove a clever but problematic scheme for retrieving package metadata, and replaces it with a more conventional approach (storing version info directly into __init__.py) with accompanying automation in the Makefile to make it all work. Beneficial side-effect: the import sidetrack statement should run faster now.

Release 1.1.0

2020-09-22T21:44:04Z

This release brings an API change. The previous parameter show_thread on set_debug(...) has been removed in favor of a new, more general parameter: extra. This new parameter can be used to add text to every debug output line. The text can contain Python logging package % format codes; thus, it can be used to achieve the same effect as the show_thread parameter by using a value that contains %(threadName)s. More importantly, extra provides more capabilities, and is thus a more general solution than the show_thread parameter was.

Other changes include the following:

Allow the destination parameter for set_debug(...) to be a stream, not just '-' or a file.
Fix documentation to explain that the default output is sys.stderr, not sys.stdout.
Additional documentation fixes and edits.

The file CHANGES contains a more complete change log that includes information about previous releases.

Release 1.0.1

2020-09-18T01:48:44Z

The following are the changes in this release:

Minor edits to the README file for grammar and clarity
Overhaul of the Makefile for greater release automation

There are no functional or other changes in this release.

Release 1.0.0

2020-09-16T22:18:43Z

This is the first complete release of Sidetrack, a simple debug tracing package for Python. Please see the front page of the GitHub project repository for more information about Sidetrack and how to use it.