#!/usr/bin/env python
from setuptools import setup
setup(
  name = 'cs.pfx',
  description = 'Easy context prefixes for messages.',
  author = 'Cameron Simpson',
  author_email = 'cs@cskk.id.au',
  version = '20191004',
  url = 'https://bitbucket.org/cameron_simpson/css/commits/all',
  classifiers = ['Programming Language :: Python', 'Programming Language :: Python :: 2', '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+)'],
  include_package_data = True,
  install_requires = ['cs.deco', 'cs.py3', 'cs.x'],
  keywords = ['python2', 'python3'],
  license = 'GNU General Public License v3 or later (GPLv3+)',
  long_description = '*Latest release 20191004*:\n@pfx_method: new optional `use_str` parameter to use str(self) instead of type(self).__name__; now requires @cs.deco.decorator\n\nDynamic message prefixes providing execution context.\n\nThe primary facility here is Pfx,\na context manager which maintains a per thread stack of context prefixes.\n\nUsage is like this:\n\n    from cs.pfx import Pfx\n    ...\n    def parser(filename):\n      with Pfx("parse(%r)", filename):\n        with open(filename) as f:\n          for lineno, line in enumerate(f, 1):\n            with Pfx("%d", lineno) as P:\n              if line_is_invalid(line):\n                raise ValueError("problem!")\n              P.info("line = %r", line)\n\nThis produces log messages like:\n\n    datafile: 1: line = \'foo\\n\'\n\nand exception messages like:\n\n    datafile: 17: problem!\n\nwhich lets one put just the relevant complaint in exception and log\nmessages and get useful calling context on the output.\nThis does make for wordier logs and exceptions\nbut used with a little discretion produces far more debuggable results.\n\n## Function `gen(func)`\n\nDecorator for generators to manage the Pfx stack.\n\nBefore running the generator the current stack height is\nnoted.  After yield, the stack above that height is trimmed\nand saved, and the value yielded.  On recommencement the saved\nstack is reapplied to the current stack (which may have\nchanged) and the generator continued.\n\n## Class `Pfx`\n\nA context manager to maintain a per-thread stack of message prefixes.\n\n### Method `Pfx.__init__(self, mark, *args, **kwargs)`\n\nInitialise a new Pfx instance.\n\nParameters:\n* `mark`: message prefix string\n* `args`: if not empty, apply to the prefix string with `%`\n* `absolute`: optional keyword argument, default False. If\n  true, this message forms the base of the message prefixes;\n  existing prefixes will be suppressed.\n* `loggers`: which loggers should receive log messages.\n\n*Note*:\nthe `mark` and `args` are only combined if the `Pfx` instance gets used,\nfor example for logging or to annotate an exception.\nOtherwise, they are not combined.\nTherefore the values interpolated are as they are when the `Pfx` is used,\nnot necessarily as they were when the `Pfx` was created.\nIf `args` is subject to change and you require the original values,\napply them to `mark` immediately, for example:\n\n    with Pfx(\'message %s ...\' % (arg1, arg2, ...)):\n\nThis is a bit more expensive, and the common usage is:\n\n    with Pfx(\'message %s ...\', arg1, arg2, ...):\n\n## Function `pfx(func)`\n\nDecorator for functions that should run inside:\n\n    with Pfx(func_name):\n\nUse:\n\n    @pfx\n    def f(...):\n\n## Function `pfx_iter(tag, iterable)`\n\nWrapper for iterables to prefix exceptions with `tag`.\n\n## Function `pfx_method(*da, **dkw)`\n\nDecorator to provide a `Pfx` context for an instance method prefixing\n*classname.methodname*\n(or *str(self).methodname* if `use_str` is true).\n\n## Class `PfxCallInfo`\n\nMRO: `Pfx`  \nSubclass of Pfx to insert current function an caller into messages.\n\n## Function `pfxtag(tag, loggers=None)`\n\nDecorator for functions that should run inside:\n\n    with Pfx(tag, loggers=loggers):\n\nUse:\n\n    @pfxtag(tag)\n    def f(...):\n\n## Function `PfxThread(target=None, **kw)`\n\nFactory function returning a Thread\nwhich presents the current prefix as context.\n\n## Function `prefix()`\n\nReturn the current Pfx prefix.\n\n## Function `PrePfx(tag, *args)`\n\nPush a temporary value for Pfx._state._ur_prefix to enloundenify messages.\n\n## Function `XP(msg, *args, **kwargs)`\n\nVariation on `cs.x.X`\nwhich prefixes the message with the current Pfx prefix.\n\n## Function `XX(prepfx, msg, *args, **kwargs)`\n\nTrite wrapper for `XP()` to transiently insert a leading prefix string.\n\nExample:\n\n    XX("NOTE!", "some message")\n\n\n\n# Release Log\n\n*Release 20191004*:\n@pfx_method: new optional `use_str` parameter to use str(self) instead of type(self).__name__; now requires @cs.deco.decorator\n\n*Release 20190905*:\nPfx.__exit__: simplify prefixify_exc() logic, prefixify all suitable attributes.\nNew @pfx_method decorator for instance methods.\n\n*Release 20190607*:\nPfx.__exit__ improved exception attribute handling.\n\n*Release 20190403*:\nDebugging aid: Pfx.umark: emit stack traceback on format conversion error.\n\n*Release 20190327*:\n@pfx: set __name__ on the wrapper function.\nBugfix some references to the internal prefixify function.\n\n*Release 20190324*:\nPfx.__exit__: apply the prefix to all the standard attributes where present, improves some message behaviour for some exception types.\n\n*Release 20181231*:\nBugfix for an infinite regress.\n\n*Release 20181109*:\nUpdate @contextmanager formalism to use try/finally for the cleanup phase.\nNew decorator @gen to manage Pfx state across generator iterations; pretty clunky.\nBetter fallback handling.\nSome docstring updates.\n\n*Release 20170910*:\nSlight linting.\n\n*Release 20170903.1*:\ncorrections to the module docstring\n\n*Release 20170903*:\nInitial release for PyPI.',
  long_description_content_type = 'text/markdown',
  package_dir = {'': 'lib/python'},
  py_modules = ['cs.pfx'],
)
