#!/usr/bin/env python
from setuptools import setup
setup(
  name = 'cs.pfx',
  author = 'Cameron Simpson',
  author_email = 'cs@cskk.id.au',
  version = '20200517',
  url = 'https://bitbucket.org/cameron_simpson/css/commits/all',
  description =
    'Easy context prefixes for messages.',
  long_description =
    ('Dynamic message prefixes providing execution context.\n'    
 '\n'    
 '*Latest release 20200517*:\n'    
 '* @pfx: handle normal functions and also generators, improve behaviour with '    
 'the wrapped docstring.\n'    
 '* @pfx_method: @pfx for methods.\n'    
 '* @pfxtag obsoleted by new @pfx.\n'    
 '\n'    
 'The primary facility here is Pfx,\n'    
 'a context manager which maintains a per thread stack of context prefixes.\n'    
 'There are also decorators for functions.\n'    
 '\n'    
 'Usage is like this:\n'    
 '\n'    
 '    from cs.logutils import setup_logging, info\n'    
 '    from cs.pfx import Pfx\n'    
 '    ...\n'    
 '    setup_logging()\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'    
 '              info("line = %r", line)\n'    
 '\n'    
 'This produces log messages like:\n'    
 '\n'    
 "    datafile: 1: line = 'foo\\n'\n"    
 '\n'    
 'and exception messages like:\n'    
 '\n'    
 '    datafile: 17: problem!\n'    
 '\n'    
 'which lets one put just the relevant complaint in exception and log\n'    
 'messages and get useful calling context on the output.\n'    
 'This does make for wordier logs and exceptions\n'    
 'but used with a little discretion produces far more debuggable results.\n'    
 '\n'    
 '## Function `gen(func)`\n'    
 '\n'    
 'Decorator for generators to manage the Pfx stack.\n'    
 '\n'    
 'Before running the generator the current stack height is\n'    
 'noted.  After yield, the stack above that height is trimmed\n'    
 'and saved, and the value yielded.  On recommencement the saved\n'    
 'stack is reapplied to the current stack (which may have\n'    
 'changed) and the generator continued.\n'    
 '\n'    
 '## Class `Pfx`\n'    
 '\n'    
 'A context manager to maintain a per-thread stack of message prefixes.\n'    
 '\n'    
 '### Method `Pfx.__init__(self, mark, *args, **kwargs)`\n'    
 '\n'    
 'Initialise a new Pfx instance.\n'    
 '\n'    
 'Parameters:\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'    
 '  earlier prefixes will be suppressed.\n'    
 '* `loggers`: which loggers should receive log messages.\n'    
 '\n'    
 '*Note*:\n'    
 'the `mark` and `args` are only combined if the `Pfx` instance gets used,\n'    
 'for example for logging or to annotate an exception.\n'    
 'Otherwise, they are not combined.\n'    
 'Therefore the values interpolated are as they are when the `Pfx` is used,\n'    
 'not necessarily as they were when the `Pfx` was created.\n'    
 'If the `args` are subject to change and you require the original values,\n'    
 'apply them to `mark` immediately, for example:\n'    
 '\n'    
 "    with Pfx('message %s ...' % (arg1, arg2, ...)):\n"    
 '\n'    
 'This is a bit more expensive as it incurs the formatting cost\n'    
 'whenever you enter the `with` clause.\n'    
 'The common usage is:\n'    
 '\n'    
 "    with Pfx('message %s ...', arg1, arg2, ...):\n"    
 '\n'    
 '## Function `pfx(*da, **dkw)`\n'    
 '\n'    
 'General purpose @pfx for generators, methods etc.\n'    
 'Pfx needs a .overPfx attribute to hook up chained Pfx stacks.\n'    
 '\n'    
 'Parameters:\n'    
 '* `func`: the function to decorate\n'    
 '* `message`: optional prefix to use instead of the function name\n'    
 '* `message_args`: optional arguments to embed in the preifx using `%`\n'    
 '\n'    
 'Example usage:\n'    
 '\n'    
 '    @pfx\n'    
 '    def f(....):\n'    
 '        ....\n'    
 '\n'    
 '## Function `pfx_iter(tag, iterable)`\n'    
 '\n'    
 'Wrapper for iterables to prefix exceptions with `tag`.\n'    
 '\n'    
 '## Function `pfx_method(*da, **dkw)`\n'    
 '\n'    
 'Decorator 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'    
 'Example usage:\n'    
 '\n'    
 '    class O:\n'    
 '        @pfx_method\n'    
 '        def foo(self, .....):\n'    
 '            ....\n'    
 '\n'    
 '## Class `PfxCallInfo(Pfx)`\n'    
 '\n'    
 'Subclass of Pfx to insert current function an caller into messages.\n'    
 '\n'    
 '## Function `PfxThread(target=None, **kw)`\n'    
 '\n'    
 'Factory function returning a Thread\n'    
 'which presents the current prefix as context.\n'    
 '\n'    
 '## Function `prefix()`\n'    
 '\n'    
 'Return the current Pfx prefix.\n'    
 '\n'    
 '## Function `PrePfx(tag, *args)`\n'    
 '\n'    
 'Push a temporary value for Pfx._state._ur_prefix to enloundenify messages.\n'    
 '\n'    
 '## Function `XP(msg, *args, **kwargs)`\n'    
 '\n'    
 'Variation on `cs.x.X`\n'    
 'which prefixes the message with the current Pfx prefix.\n'    
 '\n'    
 '## Function `XX(prepfx, msg, *args, **kwargs)`\n'    
 '\n'    
 'Trite wrapper for `XP()` to transiently insert a leading prefix string.\n'    
 '\n'    
 'Example:\n'    
 '\n'    
 '    XX("NOTE!", "some message")\n'    
 '\n'    
 '# Release Log\n'    
 '\n'    
 '\n'    
 '\n'    
 '*Release 20200517*:\n'    
 '* @pfx: handle normal functions and also generators, improve behaviour with '    
 'the wrapped docstring.\n'    
 '* @pfx_method: @pfx for methods.\n'    
 '* @pfxtag obsoleted by new @pfx.\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*:\n'    
 '* Pfx.__exit__: simplify prefixify_exc() logic, prefixify all suitable '    
 'attributes.\n'    
 '* New @pfx_method decorator for instance methods.\n'    
 '\n'    
 '*Release 20190607*:\n'    
 'Pfx.__exit__ improved exception attribute handling.\n'    
 '\n'    
 '*Release 20190403*:\n'    
 'Debugging aid: Pfx.umark: emit stack traceback on format conversion error.\n'    
 '\n'    
 '*Release 20190327*:\n'    
 '* @pfx: set __name__ on the wrapper function.\n'    
 '* Bugfix some references to the internal prefixify function.\n'    
 '\n'    
 '*Release 20190324*:\n'    
 'Pfx.__exit__: apply the prefix to all the standard attributes where present, '    
 'improves some message behaviour for some exception types.\n'    
 '\n'    
 '*Release 20181231*:\n'    
 'Bugfix for an infinite regress.\n'    
 '\n'    
 '*Release 20181109*:\n'    
 '* Update @contextmanager formalism to use try/finally for the cleanup '    
 'phase.\n'    
 '* New decorator @gen to manage Pfx state across generator iterations; pretty '    
 'clunky.\n'    
 '* Better fallback handling.\n'    
 '* Some docstring updates.\n'    
 '\n'    
 '*Release 20170910*:\n'    
 'Slight linting.\n'    
 '\n'    
 '*Release 20170903.1*:\n'    
 'corrections to the module docstring\n'    
 '\n'    
 '*Release 20170903*:\n'    
 'Initial release for PyPI.'),
  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+)'],
  install_requires = ['cs.deco', 'cs.py.func', 'cs.py3', 'cs.x'],
  keywords = ['python2', 'python3'],
  license = 'GNU General Public License v3 or later (GPLv3+)',
  long_description_content_type = 'text/markdown',
  package_dir = {'': 'lib/python'},
  py_modules = ['cs.pfx'],
)
