Metadata-Version: 2.4
Name: cs-x
Version: 20261016.1
Summary: X(), for low level debugging.
Keywords: python2,python3
Author-email: Cameron Simpson <cs@cskk.id.au>
Requires-Python: >=3
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Requires-Dist: cs.ansi_colour>=20260531
Requires-Dist: cs.gimmicks>=20260311
Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/x.py

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.
