X(), for low level debugging.
*Latest release 20240316*:
Fixed release upload artifacts.
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 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": "",
"name": "cs.x",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "python2,python3",
"author": "",
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/ac/a5/5ecca8ea32a0f6b3615e3fed5287952bec847847d6eaff1012fb5079f751/cs.x-20240316.tar.gz",
"platform": null,
"description": "X(), for low level debugging.\n\n*Latest release 20240316*:\nFixed release upload artifacts.\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 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\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "X(), for low level debugging.",
"version": "20240316",
"project_urls": {
"URL": "https://bitbucket.org/cameron_simpson/css/commits/all"
},
"split_keywords": [
"python2",
"python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "15615f20fc87e9c1ce46c97351a1f12f443359ee46b4e488f8c3fbd9342f58fc",
"md5": "45c0987a5759900b6fb4094659d6ca52",
"sha256": "a0c1bf3c47b390138471e6ce5d08257b468ca3775255f21f86d52def403053cc"
},
"downloads": -1,
"filename": "cs.x-20240316-py3-none-any.whl",
"has_sig": false,
"md5_digest": "45c0987a5759900b6fb4094659d6ca52",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5176,
"upload_time": "2024-03-16T06:58:02",
"upload_time_iso_8601": "2024-03-16T06:58:02.512850Z",
"url": "https://files.pythonhosted.org/packages/15/61/5f20fc87e9c1ce46c97351a1f12f443359ee46b4e488f8c3fbd9342f58fc/cs.x-20240316-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aca55ecca8ea32a0f6b3615e3fed5287952bec847847d6eaff1012fb5079f751",
"md5": "bbb14d2711ab1e0c93f3b6074283a331",
"sha256": "a46416a1da723b20570e3afdfc83f99a9463bc521b08cafc94b38edf8e720785"
},
"downloads": -1,
"filename": "cs.x-20240316.tar.gz",
"has_sig": false,
"md5_digest": "bbb14d2711ab1e0c93f3b6074283a331",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 4560,
"upload_time": "2024-03-16T06:58:04",
"upload_time_iso_8601": "2024-03-16T06:58:04.496093Z",
"url": "https://files.pythonhosted.org/packages/ac/a5/5ecca8ea32a0f6b3615e3fed5287952bec847847d6eaff1012fb5079f751/cs.x-20240316.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-16 06:58:04",
"github": false,
"gitlab": false,
"bitbucket": true,
"codeberg": false,
"bitbucket_user": "cameron_simpson",
"bitbucket_project": "css",
"lcname": "cs.x"
}
JSON