cs-x 20261016__py3-none-any.whl

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)

cs_x-20261016.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,4 @@
+cs/x.py,sha256=nWeTzPT1sZPQqoWrpFYrY7c9V_8fPVCagigif-FhJak,5265
+cs_x-20261016.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+cs_x-20261016.dist-info/METADATA,sha256=vZg5PrBkMUlPKoT_k9LSnCQW4LGV2GyiPnG94w4rfTw,3614
+cs_x-20261016.dist-info/RECORD,,

cs_x-20261016.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.12.0
+Root-Is-Purelib: true
+Tag: py3-none-any