Promise
=======
This is a implementation of Promises in Python. It is a super set of
Promises/A+ designed to have readable, performant code and to provide
just the extensions that are absolutely necessary for using promises in
Python.
Its fully compatible with the `Promises/A+
spec <http://promises-aplus.github.io/promises-spec/>`__
|travis| |pypi| |coveralls|
Installation
------------
::
$ pip install promise
Usage
-----
The example below shows how you can load the promise library. It then
demonstrates creating a promise from scratch. You simply call
``Promise(fn)``. There is a complete specification for what is returned
by this method in
`Promises/A+ <http://promises-aplus.github.com/promises-spec/>`__.
.. code:: python
from promise import Promise
promise = Promise(
lambda resolve, reject: resolve('RESOLVED!')
)
API
---
Before all examples, you will need:
.. code:: python
from promise import Promise
Promise(resolver)
~~~~~~~~~~~~~~~~~
This creates and returns a new promise. ``resolver`` must be a function.
The ``resolver`` function is passed two arguments:
1. ``resolve`` should be called with a single argument. If it is called
with a non-promise value then the promise is fulfilled with that
value. If it is called with a promise (A) then the returned promise
takes on the state of that new promise (A).
2. ``reject`` should be called with a single argument. The returned
promise will be rejected with that argument.
Class Methods
~~~~~~~~~~~~~
These methods are invoked by calling ``Promise.methodName``.
Promise.resolve(value)
^^^^^^^^^^^^^^^^^^^^^^
Converts values and foreign promises into Promises/A+ promises. If you
pass it a value then it returns a Promise for that value. If you pass it
something that is close to a promise (such as a jQuery attempt at a
promise) it returns a Promise that takes on the state of ``value``
(rejected or fulfilled).
Promise.reject(value)
^^^^^^^^^^^^^^^^^^^^^
Returns a rejected promise with the given value.
Promise.all(list)
^^^^^^^^^^^^^^^^^
Returns a promise for a list. If it is called with a single argument
then this returns a promise for a copy of that list with any promises
replaced by their fulfilled values. e.g.
.. code:: python
p = Promise.all([Promise.resolve('a'), 'b', Promise.resolve('c')]) \
.then(lambda res: res == ['a', 'b', 'c'])
assert p.get() is True
Promise.cast(obj)
^^^^^^^^^^^^^^^^^
This function wraps the ``obj`` act as a ``Promise`` if possible. Python
``Future``\ s are supported, with a callback to ``promise.done`` when
resolved. Have the same effects as ``Promise.resolve(obj)``.
Promise.for\_dict(d)
^^^^^^^^^^^^^^^^^^^^
A special function that takes a dictionary of promises and turns them
into a promise for a dictionary of values. In other words, this turns an
dictionary of promises for values into a promise for a dictionary of
values.
Promise.is\_thenable(obj)
^^^^^^^^^^^^^^^^^^^^^^^^^
This function checks if the ``obj`` is a ``Promise``, or could be
``cast``\ ed.
Promise.promisify(func)
^^^^^^^^^^^^^^^^^^^^^^^
This function wraps the result of calling ``func`` in a ``Promise``
instance.
Instance Methods
~~~~~~~~~~~~~~~~
These methods are invoked on a promise instance by calling
``myPromise.methodName``
promise.then(did\_fulfill, did\_reject)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This method follows the `Promises/A+
spec <http://promises-aplus.github.io/promises-spec/>`__. It explains
things very clearly so I recommend you read it.
Either ``did_fulfill`` or ``did_reject`` will be called and they will
not be called more than once. They will be passed a single argument and
will always be called asynchronously (in the next turn of the event
loop).
If the promise is fulfilled then ``did_fulfill`` is called. If the
promise is rejected then ``did_reject`` is called.
The call to ``.then`` also returns a promise. If the handler that is
called returns a promise, the promise returned by ``.then`` takes on the
state of that returned promise. If the handler that is called returns a
value that is not a promise, the promise returned by ``.then`` will be
fulfilled with that value. If the handler that is called throws an
exception then the promise returned by ``.then`` is rejected with that
exception.
promise.catch(did\_reject)
^^^^^^^^^^^^^^^^^^^^^^^^^^
Sugar for ``promise.then(None, did_reject)``, to mirror ``catch`` in
synchronous code.
promise.done(did\_fulfill, did\_reject)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The same semantics as ``.then`` except that it does not return a promise
and any exceptions are re-thrown so that they can be logged (crashing
the application in non-browser environments)
Contributing
============
After cloning this repo, ensure dependencies are installed by running:
.. code:: sh
pip install -e ".[test]"
After developing, the full test suite can be evaluated by running:
.. code:: sh
py.test tests --cov=promise --benchmark-skip # Use -v -s for verbose mode
You can also run the benchmarks with:
.. code:: sh
py.test tests --benchmark-only
Static type checking
--------------------
Python type annotations are very useful for making sure we use the
libary the way is intended.
You can run ``mypy`` static type checker:
.. code:: sh
pip install mypy
mypy promise --ignore-missing-imports
Or ``pyre``:
.. code:: sh
pip install pyre-check
pyre --source-directory promise check
Notes
=====
This package is heavily insipired in
`aplus <https://github.com/xogeny/aplus>`__.
License
-------
`MIT
License <https://github.com/syrusakbary/promise/blob/master/LICENSE>`__
.. |travis| image:: https://img.shields.io/travis/syrusakbary/promise.svg?style=flat
:target: https://travis-ci.org/syrusakbary/promise
.. |pypi| image:: https://img.shields.io/pypi/v/promise.svg?style=flat
:target: https://pypi.python.org/pypi/promise
.. |coveralls| image:: https://coveralls.io/repos/syrusakbary/promise/badge.svg?branch=master&service=github
:target: https://coveralls.io/github/syrusakbary/promise?branch=master
Raw data
{
"_id": null,
"home_page": "https://github.com/syrusakbary/promise",
"name": "promise",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "concurrent future deferred promise",
"author": "Syrus Akbary",
"author_email": "me@syrusakbary.com",
"download_url": "https://files.pythonhosted.org/packages/cf/9c/fb5d48abfe5d791cd496e4242ebcf87a4bb2e0c3dcd6e0ae68c11426a528/promise-2.3.tar.gz",
"platform": "",
"description": "Promise\n=======\n\nThis is a implementation of Promises in Python. It is a super set of\nPromises/A+ designed to have readable, performant code and to provide\njust the extensions that are absolutely necessary for using promises in\nPython.\n\nIts fully compatible with the `Promises/A+\nspec <http://promises-aplus.github.io/promises-spec/>`__\n\n|travis| |pypi| |coveralls|\n\nInstallation\n------------\n\n::\n\n $ pip install promise\n\nUsage\n-----\n\nThe example below shows how you can load the promise library. It then\ndemonstrates creating a promise from scratch. You simply call\n``Promise(fn)``. There is a complete specification for what is returned\nby this method in\n`Promises/A+ <http://promises-aplus.github.com/promises-spec/>`__.\n\n.. code:: python\n\n from promise import Promise\n\n promise = Promise(\n lambda resolve, reject: resolve('RESOLVED!')\n )\n\nAPI\n---\n\nBefore all examples, you will need:\n\n.. code:: python\n\n from promise import Promise\n\nPromise(resolver)\n~~~~~~~~~~~~~~~~~\n\nThis creates and returns a new promise. ``resolver`` must be a function.\nThe ``resolver`` function is passed two arguments:\n\n1. ``resolve`` should be called with a single argument. If it is called\n with a non-promise value then the promise is fulfilled with that\n value. If it is called with a promise (A) then the returned promise\n takes on the state of that new promise (A).\n2. ``reject`` should be called with a single argument. The returned\n promise will be rejected with that argument.\n\nClass Methods\n~~~~~~~~~~~~~\n\nThese methods are invoked by calling ``Promise.methodName``.\n\nPromise.resolve(value)\n^^^^^^^^^^^^^^^^^^^^^^\n\nConverts values and foreign promises into Promises/A+ promises. If you\npass it a value then it returns a Promise for that value. If you pass it\nsomething that is close to a promise (such as a jQuery attempt at a\npromise) it returns a Promise that takes on the state of ``value``\n(rejected or fulfilled).\n\nPromise.reject(value)\n^^^^^^^^^^^^^^^^^^^^^\n\nReturns a rejected promise with the given value.\n\nPromise.all(list)\n^^^^^^^^^^^^^^^^^\n\nReturns a promise for a list. If it is called with a single argument\nthen this returns a promise for a copy of that list with any promises\nreplaced by their fulfilled values. e.g.\n\n.. code:: python\n\n p = Promise.all([Promise.resolve('a'), 'b', Promise.resolve('c')]) \\\n .then(lambda res: res == ['a', 'b', 'c'])\n\n assert p.get() is True\n\nPromise.cast(obj)\n^^^^^^^^^^^^^^^^^\n\nThis function wraps the ``obj`` act as a ``Promise`` if possible. Python\n``Future``\\ s are supported, with a callback to ``promise.done`` when\nresolved. Have the same effects as ``Promise.resolve(obj)``.\n\nPromise.for\\_dict(d)\n^^^^^^^^^^^^^^^^^^^^\n\nA special function that takes a dictionary of promises and turns them\ninto a promise for a dictionary of values. In other words, this turns an\ndictionary of promises for values into a promise for a dictionary of\nvalues.\n\nPromise.is\\_thenable(obj)\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThis function checks if the ``obj`` is a ``Promise``, or could be\n``cast``\\ ed.\n\nPromise.promisify(func)\n^^^^^^^^^^^^^^^^^^^^^^^\n\nThis function wraps the result of calling ``func`` in a ``Promise``\ninstance.\n\nInstance Methods\n~~~~~~~~~~~~~~~~\n\nThese methods are invoked on a promise instance by calling\n``myPromise.methodName``\n\npromise.then(did\\_fulfill, did\\_reject)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThis method follows the `Promises/A+\nspec <http://promises-aplus.github.io/promises-spec/>`__. It explains\nthings very clearly so I recommend you read it.\n\nEither ``did_fulfill`` or ``did_reject`` will be called and they will\nnot be called more than once. They will be passed a single argument and\nwill always be called asynchronously (in the next turn of the event\nloop).\n\nIf the promise is fulfilled then ``did_fulfill`` is called. If the\npromise is rejected then ``did_reject`` is called.\n\nThe call to ``.then`` also returns a promise. If the handler that is\ncalled returns a promise, the promise returned by ``.then`` takes on the\nstate of that returned promise. If the handler that is called returns a\nvalue that is not a promise, the promise returned by ``.then`` will be\nfulfilled with that value. If the handler that is called throws an\nexception then the promise returned by ``.then`` is rejected with that\nexception.\n\npromise.catch(did\\_reject)\n^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nSugar for ``promise.then(None, did_reject)``, to mirror ``catch`` in\nsynchronous code.\n\npromise.done(did\\_fulfill, did\\_reject)\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThe same semantics as ``.then`` except that it does not return a promise\nand any exceptions are re-thrown so that they can be logged (crashing\nthe application in non-browser environments)\n\nContributing\n============\n\nAfter cloning this repo, ensure dependencies are installed by running:\n\n.. code:: sh\n\n pip install -e \".[test]\"\n\nAfter developing, the full test suite can be evaluated by running:\n\n.. code:: sh\n\n py.test tests --cov=promise --benchmark-skip # Use -v -s for verbose mode\n\nYou can also run the benchmarks with:\n\n.. code:: sh\n\n py.test tests --benchmark-only\n\nStatic type checking\n--------------------\n\nPython type annotations are very useful for making sure we use the\nlibary the way is intended.\n\nYou can run ``mypy`` static type checker:\n\n.. code:: sh\n\n pip install mypy\n mypy promise --ignore-missing-imports\n\nOr ``pyre``:\n\n.. code:: sh\n\n pip install pyre-check\n pyre --source-directory promise check\n\nNotes\n=====\n\nThis package is heavily insipired in\n`aplus <https://github.com/xogeny/aplus>`__.\n\nLicense\n-------\n\n`MIT\nLicense <https://github.com/syrusakbary/promise/blob/master/LICENSE>`__\n\n.. |travis| image:: https://img.shields.io/travis/syrusakbary/promise.svg?style=flat\n :target: https://travis-ci.org/syrusakbary/promise\n.. |pypi| image:: https://img.shields.io/pypi/v/promise.svg?style=flat\n :target: https://pypi.python.org/pypi/promise\n.. |coveralls| image:: https://coveralls.io/repos/syrusakbary/promise/badge.svg?branch=master&service=github\n :target: https://coveralls.io/github/syrusakbary/promise?branch=master\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Promises/A+ implementation for Python",
"version": "2.3",
"split_keywords": [
"concurrent",
"future",
"deferred",
"promise"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "28a14b6bcf3bd7d351cb158621600faf",
"sha256": "dfd18337c523ba4b6a58801c164c1904a9d4d1b1747c7d5dbf45b693a49d93d0"
},
"downloads": -1,
"filename": "promise-2.3.tar.gz",
"has_sig": false,
"md5_digest": "28a14b6bcf3bd7d351cb158621600faf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19534,
"upload_time": "2019-12-18T07:31:43",
"upload_time_iso_8601": "2019-12-18T07:31:43.070499Z",
"url": "https://files.pythonhosted.org/packages/cf/9c/fb5d48abfe5d791cd496e4242ebcf87a4bb2e0c3dcd6e0ae68c11426a528/promise-2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-12-18 07:31:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "syrusakbary",
"github_project": "promise",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"lcname": "promise"
}
JSON
