#!/usr/bin/env python
from setuptools import setup
setup(
  name = 'cs.later',
  description = 'Queue functions for execution later in priority and time order.',
  author = 'Cameron Simpson',
  author_email = 'cs@cskk.id.au',
  version = '20181109',
  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 (GPLv3)'],
  install_requires = ['cs.debug', 'cs.excutils', 'cs.logutils', 'cs.pfx', 'cs.py.func', 'cs.queues', 'cs.result', 'cs.seq', 'cs.threads', 'cs.x'],
  keywords = ['python2', 'python3'],
  long_description = "Queue functions for execution later in priority and time order.\n\nI use Later objects for convenient queuing of functions whose\nexecution occurs later in a priority order with capacity constraints.\n\nWhy not futures?\nI already had this before futures came out,\nI prefer its naming scheme and interface,\nand futures did not seem to support prioritising execution.\n\nUse is simple enough: create a Later instance and typically queue\nfunctions with the .defer() method::\n\n    L = Later(4)      # a Later with a parallelism of 4\n    ...\n    LF = L.defer(func, *args, **kwargs)\n    ...\n    x = LF()          # collect result\n\nThe .defer method and its siblings return a LateFunction,\nwhich is a subclass of cs.result.Result.\nAs such it is a callable, so to collect the result you just call the LateFunction.\n\n## Function `capacity(func)`\n\nDecorator for functions which wish to manage concurrent requests.\nThe caller must provide a `capacity` keyword arguments which\nis either a Later instance or an int; if an int a Later with\nthat capacity will be made.\nThe Later will be passed into the inner function as the\n`capacity` keyword argument.\n\n## Function `defer(func, *a, **kw)`\n\nQueue a function using the current default Later.\nReturn the LateFunction.\n\n## Class `LateFunction`\n\nMRO: `cs.result._PendingFunction`, `cs.result.Result`  \nState information about a pending function.\nA LateFunction is callable, so a synchronous call can be done like this:\n\n  def func():\n    return 3\n  L = Later(4)\n  LF = L.defer()\n  x = LF()\n  print(x)        # prints 3\n\nUsed this way, if the called function raises an exception it is visible:\n\n  LF = L.defer()\n  try:\n    x = LF()\n  except SomeException as e:\n    # handle the exception ...\n\nTo avoid handling exceptions with try/except the .wait()\nmethod should be used:\n\n  LF = L.defer()\n  x, exc_info = LF.wait()\n  if exc_info:\n    # handle exception\n    exc_type, exc_value, exc_traceback = exc_info\n    ...\n  else:\n    # use `x`, the function result\n\nTODO: .cancel()\n      timeout for wait()\n\n## Class `LatePool`\n\nA context manager after the style of subprocess.Pool but with deferred completion.\nExample usage:\n\n  L = Later(4)    # a 4 thread Later\n  with LatePool(L) as LP:\n    # several calls to LatePool.defer, perhaps looped\n    LP.defer(func, *args, **kwargs)\n    LP.defer(func, *args, **kwargs)\n  # now we can LP.join() to block for all LateFunctions\n  #\n  # or iterate over LP to collect LateFunctions as they complete\n  for LF in LP:\n    result = LF()\n    print(result)\n\n## Class `Later`\n\nA management class to queue function calls for later execution.\n\nMethods are provided for submitting functions to run ASAP or\nafter a delay or after other pending functions. These methods\nreturn LateFunctions, a subclass of cs.result.Result.\n\nA Later instance' closes method closes the Later for further\nsubmission.\nShutdown does not imply that all submitted functions have\ncompleted or even been dispatched.\nCallers may wait for completion and optionally cancel functions.\n\n## Function `retry(retry_interval, func, *a, **kw)`\n\nCall the callable `func` with the supplied arguments.\nIf it raises RetryError, sleep(`retry_interval`) and call\nagain until it does not raise RetryError.\n\n## Class `RetryError`\n\nMRO: `builtins.Exception`, `builtins.BaseException`  \nException raised by functions which should be resubmitted to the queue.",
  long_description_content_type = 'text/markdown',
  package_dir = {'': 'lib/python'},
  py_modules = ['cs.later'],
)
