Package: cs.x
X(), for low level debugging.Latest release 20240201:
Doc updates.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 tosys.stderrbut accepts an optional
keyword argumentfileto specify a different filelike object.The following globals further tune its behaviour,
absent thefile=parameter:X_default_colour: if set, messages will be ANSI coloured usingcs.ansi_colour.colouriseX_discard: if true then discard the message.
Otherwise write the message tosys.stderr.X_discard's default value isnot sys.stderr.isatty().X_logger: if notNonethen 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 setsX_default_colour.$CS_X_LOGGER:
if present, an empty value setsX_loggerto the root logger
and a nonempty value names a logger.$CS_X_VIA_TTY: if missing or empty,X_via_ttywill be false.
Otherwise,
if$CS_X_VIA_TTYhas a nonempty value which is a full path
to an existing filesystem object (typically a tty)
then is will be used forX_via_tty,
otherwiseX_via_ttywill be set to'/dev/tty'.
This is handy for getting debugging out of test suites,
which often divertsys.stderr.FunctionX(msg, *args, **kw)Unconditionally write the messagemsg.If there are positional arguments aftermsg,
formatmsgusing %-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.Iffileis notNone, write to it unconditionally.
Otherwise, the following globals are consulted in order:X_logger: if notNonethen log a warning to that loggerX_via_tty: if true then append the message to the path it containsX_discard: if true then discard the message
Otherwise write the message tosys.stderr.X_loggerisNoneby default.X_via_ttyis initialised from the environment variable$CS_X_VIA_TTY.X_discardis true unlesssys.stderr.isatty()is true.FunctionY(msg, *a, **kw)Wrapper forX()rendering in yellow.Release LogRelease 20240201:
Doc updates.Release 20231129:
New $CS_X_LOGGER environment variable to direct messages to a logger.Release 20230331:
Move the open-tty-for-append hacks into cs.gimmicks.open_append, fix unclosed file handle.Release 20230218:
Accomodate idiotic Linux /dev/tty open semantics.Release 20221118:
Tweak for open of /dev/tty, still not properly resolved.Release 20220918:Drop Xtty(), obsolete.X(): special handling for unseeking output files - I've had a Linux system moan about opening /dev/tty for append.Release 20211208:
X_via_tty: now accept full path to a tty in $CS_X_VIA_TTY to aid messaging to other terminals.Release 20210123:
X: honour new $CS_X_COLOUR environment variable setting the default colour, default uncoloured.Release 20201227:
New Y() which calls X(...,colour=yellow) - I now often gofrom cs.x import Y as X.Release 20201102:Set X_via_tty if $CS_X_VIA_TTY.Put X() into builtins if $CS_X_BUILTIN.Release 20181231:X: trivial ANSI colour support via newcolourkeyword argument.New global X_discard, False unless sys.stderr.isatty.Release 20180726:
doco improvementsRelease 20170902:
Move X() into its own module, used for ad hoc debugging everywhere.Release 20170707.3:
tweak DISTINFORelease 20170707.2:
Doc tweak.Release 20170707.1:
Added README.Release 20170707:
Separate X() out into new module cs.x for cheap import.