X(), for low level debugging.

X() is my function for low level ad hoc debug messages. It takes a message and optional format arguments for use with %. It is presented here in its own module for reuse:

from cs.x import X
...
X("foo: x=%s, a=%r", x, a)

It normally writes directly to sys.stderr but accepts an optional keyword argument file to specify a different filelike object.

The following globals further tune its behaviour, absent the file= parameter:

• X_default_colour: if set, messages will be ANSI coloured using cs.ansi_colour.colourise
• X_discard: if true then discard the message. Otherwise write the message to sys.stderr. X_discard's default value is not sys.stderr.isatty().
• X_logger: if not None then log a warning to that logger.
• X_via_tty: if true then a pathname to which to append messages.

The following environment variables affect the initial values of the globals:

• $CS_X_COLOUR: this sets X_default_colour.
• $CS_X_LOGGER: if present, an empty value sets X_logger to the root logger and a nonempty value names a logger.
• $CS_X_VIA_TTY: if missing or empty, X_via_tty will be false. Otherwise, if $CS_X_VIA_TTY has a nonempty value which is a full path to an existing filesystem object (typically a tty) then is will be used for X_via_tty, otherwise X_via_tty will be set to '/dev/tty'. This is handy for getting debugging out of test suites, which often divert sys.stderr.

Short summary:

• X: Unconditionally write the message msg.

• Y: Wrapper for X() rendering in yellow.

Functions

X(msg, *args, file=None, colour=None)

Unconditionally write the message msg.

If there are positional arguments after msg, format msg using %-expansion with those arguments.

Keyword arguments:

• file: optional keyword argument specifying the output file.
• colour: optional text colour. If specified, surround the message with ANSI escape sequences to render the text in that colour.

If file is not None, write to it unconditionally. Otherwise, the following globals are consulted in order:

• X_logger: if not None then log a warning to that logger
• X_via_tty: if true then append the message to the path it contains
• X_discard: if true then discard the message Otherwise write the message to sys.stderr.

X_logger is None by default. X_via_tty is initialised from the environment variable $CS_X_VIA_TTY. X_discard is true unless sys.stderr.isatty() is true.

Y(msg, *a, **kw)

Wrapper for X() rendering in yellow.