cs-x 20261016__tar.gz

cs_x-20261016/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: cs-x
+Version: 20261016
+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.

cs_x-20261016/pyproject.toml

@@ -0,0 +1,123 @@
+[project]
+name = "cs-x"
+description = "X(), for low level debugging."
+authors = [
+    { name = "Cameron Simpson", email = "cs@cskk.id.au" },
+]
+keywords = [
+    "python2",
+    "python3",
+]
+dependencies = [
+    "cs.ansi_colour>=20260531",
+    "cs.gimmicks>=20260311",
+]
+classifiers = [
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+]
+version = "20261016"
+requires-python = ">=3"
+
+[project.license]
+text = "GNU General Public License v3 or later (GPLv3+)"
+
+[project.urls]
+"Monorepo Hg/Mercurial Mirror" = "https://hg.sr.ht/~cameron-simpson/css"
+"Monorepo Git Mirror" = "https://github.com/cameron-simpson/css"
+"MonoRepo Commits" = "https://bitbucket.org/cameron_simpson/css/commits/branch/main"
+Source = "https://github.com/cameron-simpson/css/blob/main/lib/python/cs/x.py"
+
+[project.readme]
+text = """
+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."""
+content-type = "text/markdown"
+
+[build-system]
+build-backend = "flit_core.buildapi"
+requires = [
+    "flit_core >=3.2,<4",
+]
+
+[tool.flit.module]
+name = "cs.x"

cs_x-20261016/src/cs/x.py

@@ -0,0 +1,182 @@
+#!/usr/bin/python
+#
+# Just my X debugging function.
+#   - Cameron Simpson <cs@cskk.id.au>
+#
+
+'''
+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`.
+'''
+
+import logging
+import os
+import os.path
+import sys
+
+from cs.ansi_colour import colourise
+from cs.gimmicks import open_append
+
+__version__ = '20261016'
+
+DISTINFO = {
+    'keywords': ["python2", "python3"],
+    'classifiers': [
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3",
+    ],
+    'install_requires': [
+        'cs.ansi_colour',
+        'cs.gimmicks',
+    ],
+    'python_requires':
+    '>=3',
+}
+
+# discard output? the default if sys.stderr is not a tty
+try:
+  isatty = sys.stderr.isatty
+except AttributeError:
+  X_discard = True
+else:
+  X_discard = not isatty()
+# set to a logger to log as a warning
+X_logger = os.environ.get('CS_X_LOGGER')
+if X_logger is not None:
+  X_Logger = logging.getLogger(X_logger or None)
+# colouring
+X_default_colour = os.environ.get('CS_X_COLOUR')
+
+# pylint: disable=too-many-branches
+def X(msg, *args, file=None, colour=None):  # noqa: N802
+  ''' 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.
+  '''
+  if colour is None:
+    colour = X_default_colour
+  if args:
+    try:
+      msg = msg % args
+    except TypeError as e:
+      X("X(%r, *%r): %s", msg, args, e, colour='red', file=file)
+      msg = f'{msg} % {args!r}'
+  else:
+    msg = str(msg)
+  if colour:
+    msg = colourise(msg, colour=colour)
+  close_fp = None
+  if file is None:
+    if X_logger:
+      # NB: ignores any kwargs
+      X_logger.warning(msg)
+      return
+    if X_via_tty:
+      # NB: ignores any kwargs
+      try:
+        f = open_append(X_via_tty)
+      except (IOError, OSError) as e:  # noqa: UP024
+        X(
+            "X: cannot append to %r: %s:%s",
+            X_via_tty,
+            type(e),
+            e,
+            file=sys.stderr,
+        )
+        X(msg, file=sys.stderr)
+        return
+      close_fp = f
+    if X_discard:
+      return
+    file = sys.stderr
+  print(msg, file=file)
+  if close_fp is not None:
+    close_fp.close()
+
+# init X_via_tty (after X() because we use X() for messaging)
+env_via_tty = os.environ.get('CS_X_VIA_TTY', '')
+if not env_via_tty:
+  X_via_tty = False
+else:
+  X_via_tty = '/dev/tty'
+  if env_via_tty.startswith('/'):
+    try:
+      xfd = os.open(env_via_tty, os.O_RDONLY)
+    except OSError as e:
+      X("%s: open(%r): %s, using %r", __file__, env_via_tty, e, X_via_tty)
+    else:
+      if not os.isatty(xfd):
+        X(
+            "%s: open(%r): not a tty, using %r",
+            __file__,
+            env_via_tty,
+            X_via_tty,
+        )
+      else:
+        X_via_tty = env_via_tty
+      os.close(xfd)
+
+if os.environ.get('CS_X_BUILTIN', ''):
+  try:
+    import builtins
+  except ImportError:
+    pass
+  else:
+    builtins.X = X
+
+def Y(msg, *a, **kw):  # noqa: N802
+  ''' Wrapper for `X()` rendering in yellow.
+  '''
+  X(msg, *a, colour='yellow', **kw)