bigchaindb-driver 0.5.0

.. image:: media/repo-banner@2x.png

.. image:: https://badges.gitter.im/bigchaindb/bigchaindb-driver.svg
:alt: Join the chat at https://gitter.im/bigchaindb/bigchaindb-driver
:target: https://gitter.im/bigchaindb/bigchaindb-driver?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge


.. image:: https://img.shields.io/pypi/v/bigchaindb-driver.svg
:target: https://pypi.python.org/pypi/bigchaindb-driver

.. image:: https://img.shields.io/travis/bigchaindb/bigchaindb-driver/master.svg
:target: https://travis-ci.org/bigchaindb/bigchaindb-driver

.. image:: https://img.shields.io/codecov/c/github/bigchaindb/bigchaindb-driver/master.svg
:target: https://codecov.io/github/bigchaindb/bigchaindb-driver?branch=master

.. image:: https://readthedocs.org/projects/bigchaindb-python-driver/badge/?version=latest
:target: http://bigchaindb.readthedocs.io/projects/py-driver/en/latest/?badge=latest
:alt: Documentation Status

BigchainDB Python Driver
==========================

* Free software: Apache Software License 2.0
* Check our `Documentation`_

.. contents:: Table of Contents


Features
--------

* Support for preparing, fulfilling, and sending transactions to a BigchainDB
node.
* Retrieval of transactions by id.

Install
----------

We recommend you use a virtual environment to install and update to the latest stable version using `pip` (or `pip3`):

.. code-block:: text

pip install -U bigchaindb-driver

That will install the latest *stable* BigchainDB Python Driver. If you want to install an Alpha, Beta or RC version of the Python Driver, use something like:

.. code-block:: text

pip install -U bigchaindb_driver==0.5.0a4

The above command will install version 0.5.0a4 (Alpha 4). You can find a list of all versions in `the release history page on PyPI <https://pypi.org/project/bigchaindb-driver/#history>`_.

More information on how to install the driver can be found in the `Quickstart`_

BigchainDB Documentation
------------------------------------
* `BigchainDB Server Quickstart`_
* `The Hitchhiker's Guide to BigchainDB`_
* `HTTP API Reference`_
* `All BigchainDB Documentation`_

Usage
----------
Example: Create a divisible asset for Alice who issues 10 token to Bob so that he can use her Game Boy.
Afterwards Bob spends 3 of these tokens.

.. code-block:: python

# import BigchainDB and create an object
from bigchaindb_driver import BigchainDB
bdb_root_url = 'https://example.com:9984'
bdb = BigchainDB(bdb_root_url)

# generate a keypair
from bigchaindb_driver.crypto import generate_keypair
alice, bob = generate_keypair(), generate_keypair()

# create a digital asset for Alice
bike_token = {
'data': {
'token_for': {
'game_boy': {
'serial_number': 'LR35902'
}
},
'description': 'Time share token. Each token equals one hour of usage.',
},
}

# prepare the transaction with the digital asset and issue 10 tokens for Bob
prepared_token_tx = bdb.transactions.prepare(
operation='CREATE',
signers=alice.public_key,
recipients=[([bob.public_key], 10)],
asset=bike_token)

# fulfill and send the transaction
fulfilled_token_tx = bdb.transactions.fulfill(
prepared_token_tx,
private_keys=alice.private_key)
bdb.transactions.send_commit(fulfilled_token_tx)

# Use the tokens
# create the output and inout for the transaction
transfer_asset = {'id': bike_token_id}
output_index = 0
output = fulfilled_token_tx['outputs'][output_index]
transfer_input = {'fulfillment': output['condition']['details'],
'fulfills': {'output_index': output_index,
'transaction_id': fulfilled_token_tx[
'id']},
'owners_before': output['public_keys']}

# prepare the transaction and use 3 tokens
prepared_transfer_tx = bdb.transactions.prepare(
operation='TRANSFER',
asset=transfer_asset,
inputs=transfer_input,
recipients=[([alice.public_key], 3), ([bob.public_key], 7)])

# fulfill and send the transaction
fulfilled_transfer_tx = bdb.transactions.fulfill(
prepared_transfer_tx,
private_keys=bob.private_key)
sent_transfer_tx = bdb.transactions.send_commit(fulfilled_transfer_tx)

Compatibility Matrix
--------------------

+-----------------------+---------------------------+
| **BigchainDB Server** | **BigchainDB Driver** |
+=======================+===========================+
| ``>= 2.0.0b1`` | ``0.5.0`` |
+-----------------------+---------------------------+
| ``>= 2.0.0a3`` | ``0.5.0a4`` |
+-----------------------+---------------------------+
| ``>= 2.0.0a2`` | ``0.5.0a2`` |
+-----------------------+---------------------------+
| ``>= 2.0.0a1`` | ``0.5.0a1`` |
+-----------------------+---------------------------+
| ``>= 1.0.0`` | ``0.4.x`` |
+-----------------------+---------------------------+
| ``== 1.0.0rc1`` | ``0.3.x`` |
+-----------------------+---------------------------+
| ``>= 0.9.1`` | ``0.2.x`` |
+-----------------------+---------------------------+
| ``>= 0.8.2`` | ``>= 0.1.3`` |
+-----------------------+---------------------------+

`Although we do our best to keep the master branches in sync, there may be
occasional delays.`

License
--------
* `licenses`_ - open source & open content

Credits
-------

This package was initially created using Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template. Many BigchainDB developers have contributed since then.

.. _Documentation: https://docs.bigchaindb.com/projects/py-driver/
.. _pypi history: https://pypi.org/project/bigchaindb-driver/#history
.. _Quickstart: https://docs.bigchaindb.com/projects/py-driver/en/latest/quickstart.html
.. _BigchainDB Server Quickstart: https://docs.bigchaindb.com/projects/server/en/latest/quickstart.html
.. _The Hitchhiker's Guide to BigchainDB: https://www.bigchaindb.com/developers/guide/
.. _HTTP API Reference: https://docs.bigchaindb.com/projects/server/en/latest/http-client-server-api.html
.. _All BigchainDB Documentation: https://docs.bigchaindb.com/
.. _licenses: https://github.com/bigchaindb/bigchaindb-driver/blob/master/LICENSES.md
.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage


Changelog
=========

0.5.0 (2018-06-14)
---------------------
Added
^^^^^
* Added three new methods to send/post a transaction as discussed `here <https://github.com/bigchaindb/bigchaindb/issues/2307>`_:

* ``send_commit``
* ``send_async``
* ``send_sync``

Deprecated
^^^^^^^^^^
* ``send()`` under ``TransactionEndpoint``, and available
via ``BigchainDB.transactions``. Replaced by the above three methods:
``send_commit()``, ``send_async()``, and ``send_sync()``.


0.5.0a4 (2018-05-07)
---------------------
* `Removed dependencies from BigchainDB Server package <https://github.com/bigchaindb/bigchaindb-driver/pull/411>`_.


0.5.0a2 (2018-04-18)
---------------------
* `The default mode for sending a transaction is now commit <https://github.com/bigchaindb/bigchaindb-driver/issues/386>`_.
* `The metadata endpoint was added <https://github.com/bigchaindb/bigchaindb-driver/issues/347>`_.
* Support for BigchainDB server v2.0.0a2.


0.5.0a1 (2018-04-03)
--------------------
There were **many** changes between BigchainDB 1.3 and BigchainDB 2.0 Alpha, too many to list here. We wrote a series of blog posts to summarize most changes, especially those that affect end users and application developers:

* `Some HTTP API Changes in the Next Release <https://blog.bigchaindb.com/some-http-api-changes-in-the-next-release-49612a537b0c>`_.
* `Three Transaction Model Changes in the Next Release <https://blog.bigchaindb.com/three-transaction-model-changes-in-the-next-release-dadbac50094a>`_.


0.4.1 (2017-08-02)
------------------
Fixed
^^^^^
* Handcrafting transactions documentation. `Pull request #312
<https://github.com/bigchaindb/bigchaindb-driver/pull/312>`_.
* Quickstart guide. `Pull request #316
<https://github.com/bigchaindb/bigchaindb-driver/pull/316>`_.

0.4.0 (2017-07-05)
------------------
Added
^^^^^
* Support for BigchainDB server (HTTP API) 1.0.0.

0.3.0 (2017-06-23)
------------------
Added
^^^^^
* Support for BigchainDB server (HTTP API) 1.0.0rc1.
* Support for crypto-conditions RFC draft version 02.
* Added support for text search endpoint ``/assets?search=``

0.2.0 (2017-02-06)
------------------
Added
^^^^^
* Support for BigchainDB server 0.9.
* Methods for ``GET /`` and ``GET /api/v1``

Changed
^^^^^^^
* Node URLs, passed to ``BigchainDB()`` MUST not include the api prefix
``'/api/v1'``, e.g.:

* BEFORE: ``http://localhost:9984/api/v1``
* NOW: ``http://localhost:9984``

0.1.0 (2016-11-29)
------------------
Added
^^^^^
* Support for BigchainDB server 0.8.0.
* Support for divisible assets.

Removed
^^^^^^^
* ``create()`` and ``transfer()`` under ``TransactionEndpoint``, and available
via ``BigchainDB.transactions``. Replaced by the three "canonical"
transaction operations: ``prepare()``, ``fulfill()``, and ``send()``.
* Support for client side timestamps.


0.0.3 (2016-11-25)
------------------
Added
^^^^^
* Support for "canonical" transaction operations:

* ``prepare``
* ``fulfill``
* ``send``

Deprecated
^^^^^^^^^^
* ``create()`` and ``transfer()`` under ``TransactionEndpoint``, and available
via ``BigchainDB.transactions``. Replaced by the above three "canonical"
transaction operations: ``prepare()``, ``fulfill()``, and ``send()``.

Fixed
^^^^^
* ``BigchainDB()`` default node setting on its transport class. See commit
`0a80206 <https://github.com/bigchaindb/bigchaindb-driver/commit/0a80206407ef155d220d25a337dc9a4f51046e70>`_


0.0.2 (2016-10-28)
------------------

Added
^^^^^
* Support for BigchainDB server 0.7.0


0.0.1dev1 (2016-08-25)
----------------------

* Development (pre-alpha) release on PyPI.

Added
^^^^^
* Minimal support for ``POST`` (via ``create()`` and ``transfer()``), and
``GET`` operations on the ``/transactions`` endpoint.


0.0.1a1 (2016-08-12)
--------------------

* Planning release on PyPI.