X(), for low level debugging.
*Latest release 20240630*:
X(msg,*args): handle mismatched message and format arguments.
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`.
## Function `X(msg, *args, **kw)`
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.
## Function `Y(msg, *a, **kw)`
Wrapper for `X()` rendering in yellow.
# Release Log
*Release 20240630*:
X(msg,*args): handle mismatched message and format arguments.
*Release 20240316*:
Fixed release upload artifacts.
*Release 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 go `from 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 new `colour` keyword argument.
* New global X_discard, False unless sys.stderr.isatty.
*Release 20180726*:
doco improvements
*Release 20170902*:
Move X() into its own module, used for ad hoc debugging everywhere.
*Release 20170707.3*:
tweak DISTINFO
*Release 20170707.2*:
Doc tweak.
*Release 20170707.1*:
Added README.
*Release 20170707*:
Separate X() out into new module cs.x for cheap import.
Raw data
{
"_id": null,
"home_page": null,
"name": "cs.x",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python2, python3",
"author": null,
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/a0/b7/52dd257f63b8de8ceb844f3147071df3c2693b291bdba68ab581309c77b9/cs.x-20240630.tar.gz",
"platform": null,
"description": "X(), for low level debugging.\n\n*Latest release 20240630*:\nX(msg,*args): handle mismatched message and format arguments.\n\nX() is my function for low level ad hoc debug messages.\nIt takes a message and optional format arguments for use with `%`.\nIt is presented here in its own module for reuse:\n\n from cs.x import X\n ...\n X(\"foo: x=%s, a=%r\", x, a)\n\nIt normally writes directly to `sys.stderr` but accepts an optional\nkeyword argument `file` to specify a different filelike object.\n\nThe following globals further tune its behaviour,\nabsent the `file=` parameter:\n* `X_default_colour`: if set, messages will be ANSI coloured using\n `cs.ansi_colour.colourise`\n* `X_discard`: if true then discard the message.\n Otherwise write the message to `sys.stderr`.\n `X_discard`'s default value is `not sys.stderr.isatty()`.\n* `X_logger`: if not `None` then log a warning to that logger.\n* `X_via_tty`: if true then a pathname to which to append messages.\n\nThe following environment variables affect the initial values of the globals:\n* `$CS_X_COLOUR`: this sets `X_default_colour`.\n* `$CS_X_LOGGER`:\n if present, an empty value sets `X_logger` to the root logger\n and a nonempty value names a logger.\n* `$CS_X_VIA_TTY`: if missing or empty, `X_via_tty` will be false.\n Otherwise,\n if `$CS_X_VIA_TTY` has a nonempty value which is a full path\n to an existing filesystem object (typically a tty)\n then is will be used for `X_via_tty`,\n otherwise `X_via_tty` will be set to `'/dev/tty'`.\n This is handy for getting debugging out of test suites,\n which often divert `sys.stderr`.\n\n## Function `X(msg, *args, **kw)`\n\nUnconditionally write the message `msg`.\n\nIf there are positional arguments after `msg`,\nformat `msg` using %-expansion with those arguments.\n\nKeyword arguments:\n* `file`: optional keyword argument specifying the output file.\n* `colour`: optional text colour.\n If specified, surround the message with ANSI escape sequences\n to render the text in that colour.\n\nIf `file` is not `None`, write to it unconditionally.\nOtherwise, the following globals are consulted in order:\n* `X_logger`: if not `None` then log a warning to that logger\n* `X_via_tty`: if true then append the message to the path it contains\n* `X_discard`: if true then discard the message\nOtherwise write the message to `sys.stderr`.\n\n`X_logger` is `None` by default.\n`X_via_tty` is initialised from the environment variable `$CS_X_VIA_TTY`.\n`X_discard` is true unless `sys.stderr.isatty()` is true.\n\n## Function `Y(msg, *a, **kw)`\n\nWrapper for `X()` rendering in yellow.\n\n# Release Log\n\n\n\n*Release 20240630*:\nX(msg,*args): handle mismatched message and format arguments.\n\n*Release 20240316*:\nFixed release upload artifacts.\n\n*Release 20240201*:\nDoc updates.\n\n*Release 20231129*:\nNew $CS_X_LOGGER environment variable to direct messages to a logger.\n\n*Release 20230331*:\nMove the open-tty-for-append hacks into cs.gimmicks.open_append, fix unclosed file handle.\n\n*Release 20230218*:\nAccomodate idiotic Linux /dev/tty open semantics.\n\n*Release 20221118*:\nTweak for open of /dev/tty, still not properly resolved.\n\n*Release 20220918*:\n* Drop Xtty(), obsolete.\n* X(): special handling for unseeking output files - I've had a Linux system moan about opening /dev/tty for append.\n\n*Release 20211208*:\nX_via_tty: now accept full path to a tty in $CS_X_VIA_TTY to aid messaging to other terminals.\n\n*Release 20210123*:\nX: honour new $CS_X_COLOUR environment variable setting the default colour, default uncoloured.\n\n*Release 20201227*:\nNew Y() which calls X(...,colour=yellow) - I now often go `from cs.x import Y as X`.\n\n*Release 20201102*:\n* Set X_via_tty if $CS_X_VIA_TTY.\n* Put X() into builtins if $CS_X_BUILTIN.\n\n*Release 20181231*:\n* X: trivial ANSI colour support via new `colour` keyword argument.\n* New global X_discard, False unless sys.stderr.isatty.\n\n*Release 20180726*:\ndoco improvements\n\n*Release 20170902*:\nMove X() into its own module, used for ad hoc debugging everywhere.\n\n*Release 20170707.3*:\ntweak DISTINFO\n\n*Release 20170707.2*:\nDoc tweak.\n\n*Release 20170707.1*:\nAdded README.\n\n*Release 20170707*:\nSeparate X() out into new module cs.x for cheap import.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "X(), for low level debugging.",
"version": "20240630",
"project_urls": {
"MonoRepo Commits": "https://bitbucket.org/cameron_simpson/css/commits/all",
"Monorepo Git Mirror": "https://github.com/cameron-simpson/css",
"Monorepo Hg/Mercurial Mirror": "https://hg.sr.ht/~cameron-simpson/css",
"Source": "https://github.com/cameron-simpson/css/blob/main/lib/python/cs/x.py"
},
"split_keywords": [
"python2",
" python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c0166269362c289b85fbb5f0dcbcf810d8aa6a98cd64aa46b5fc3e91101843da",
"md5": "85fdbe63c5d81f46c031ea105ab5907a",
"sha256": "4a29702f22d694c49ad523776a5676ef57b8f22620bc274d87d59c6df67f0641"
},
"downloads": -1,
"filename": "cs.x-20240630-py3-none-any.whl",
"has_sig": false,
"md5_digest": "85fdbe63c5d81f46c031ea105ab5907a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5321,
"upload_time": "2024-06-30T00:58:38",
"upload_time_iso_8601": "2024-06-30T00:58:38.911169Z",
"url": "https://files.pythonhosted.org/packages/c0/16/6269362c289b85fbb5f0dcbcf810d8aa6a98cd64aa46b5fc3e91101843da/cs.x-20240630-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a0b752dd257f63b8de8ceb844f3147071df3c2693b291bdba68ab581309c77b9",
"md5": "dea6f6752f3d9db55e93e94c6bc342ab",
"sha256": "e16631e78be4f411499287ac23cf09784b8e1f8291911e228bcf094d9dbd906d"
},
"downloads": -1,
"filename": "cs.x-20240630.tar.gz",
"has_sig": false,
"md5_digest": "dea6f6752f3d9db55e93e94c6bc342ab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4729,
"upload_time": "2024-06-30T00:58:42",
"upload_time_iso_8601": "2024-06-30T00:58:42.074186Z",
"url": "https://files.pythonhosted.org/packages/a0/b7/52dd257f63b8de8ceb844f3147071df3c2693b291bdba68ab581309c77b9/cs.x-20240630.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-30 00:58:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cameron-simpson",
"github_project": "css",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cs.x"
}
JSON
