Merge pull request #222 from overcat/v2

v2

README.rst

@@ -31,7 +31,7 @@ py-stellar-sdk
 
 
 py-stellar-sdk is a Python library for communicating with
-a `Stellar Horizon server`_. It is used for building Stellar apps on Python. It supports Python 3.6+ as
+a `Stellar Horizon server`_. It is used for building Stellar apps on Python. It supports **Python 3.6+** as
 well as PyPy 3.6+.
 
 It provides:
@@ -113,7 +113,7 @@ A Simple Example
 
             transaction.sign(alice_keypair)
             response = await server.submit_transaction(transaction)
-         print(response)
+            print(response)
 
 
     if __name__ == "__main__":

docs/api.rst

@@ -303,6 +303,8 @@ Network
    :members:
    :inherited-members:
 
+.. _operation_list_archor:
+
 Operation
 ^^^^^^^^^
 

docs/assets.rst

@@ -0,0 +1,35 @@
+.. _assets:
+
+
+******
+Assets
+******
+
+Object of the :py:class:`Asset <stellar_sdk.asset.Asset>`
+class represents an asset in the Stellar network. Right now there are 3 possible types of assets in the Stellar network:
+
+
+* native **XLM** asset (**ASSET_TYPE_NATIVE**),
+* issued assets with asset code of maximum 4 characters (**ASSET_TYPE_CREDIT_ALPHANUM4**),
+* issued assets with asset code of maximum 12 characters (**ASSET_TYPE_CREDIT_ALPHANUM12**).
+
+To create a new native asset representation use static :py:meth:`native() <stellar_sdk.asset.Asset.native>` method:
+
+.. code-block:: python
+    :linenos:
+
+    from stellar_sdk import Asset
+    native = Asset.native()
+
+To represent an issued asset you need to create a new object of type :py:class:`Asset <stellar_sdk.asset.Asset>` with an asset code and issuer:
+
+.. code-block:: python
+    :linenos:
+
+    from stellar_sdk import Asset
+    # Creates TEST asset issued by GBBM6BKZPEHWYO3E3YKREDPQXMS4VK35YLNU7NFBRI26RAN7GI5POFBB
+    test_asset = Asset("TEST", "GBBM6BKZPEHWYO3E3YKREDPQXMS4VK35YLNU7NFBRI26RAN7GI5POFBB")
+    is_native = test_asset.is_native()  # False
+    # Creates Google stock asset issued by GBBM6BKZPEHWYO3E3YKREDPQXMS4VK35YLNU7NFBRI26RAN7GI5POFBB
+    google_stock_asset = Asset('US38259P7069', 'GBBM6BKZPEHWYO3E3YKREDPQXMS4VK35YLNU7NFBRI26RAN7GI5POFBB')
+    google_stock_asset_type = google_stock_asset.type  # credit_alphanum12

docs/building_transactions.rst

@@ -0,0 +1,96 @@
+.. _building_transactions:
+
+
+*********************
+Building Transactions
+*********************
+
+`Transactions <https://stellar.org/developers/learn/concepts/transactions.html>`_ are the commands that modify the state of the ledger.
+They include sending payments, creating offers, making account configuration changes, etc.
+
+Every transaction has a source `account <https://stellar.org/developers/learn/concepts/accounts.html>`__. This is the account
+that pays the `fee <https://stellar.org/developers/learn/concepts/fees.html>`_ and uses up a sequence number for the transaction.
+
+Transactions are made up of one or more `operations <https://stellar.org/developers/learn/concepts/operations.html>`_.
+Each operation also has a source account, which defaults to the transaction's source account.
+
+`TransactionBuilder <https://github.com/stellar/js-stellar-base/blob/master/src/transaction_builder.js>`_
+-------------------------------------------------------------------------------------------------------------
+
+The :py:class:`TransactionBuilder <stellar_sdk.transaction_builder.TransactionBuilder>` class is used to construct new transactions.
+TransactionBuilder is given an account that is used as transaction's **source account**.
+The transaction will use the current sequence number of the given :py:class:`Account <stellar_sdk.account.Account>`
+object as its sequence number and increments the given account's sequence number
+when :py:meth:`build() <stellar_sdk.transaction_builder.TransactionBuilder.build>` is called on the TransactionBuilder.
+
+Operations can be added to the transaction calling
+:py:meth:`append_operation <stellar_sdk.transaction_builder.TransactionBuilder.append_operation>` for
+each operation you wish to add to the transaction.
+See :ref:`operation_list_archor` for a list of possible operations you can add.
+:py:meth:`append_operation <stellar_sdk.transaction_builder.TransactionBuilder.append_operation>`
+returns the current :py:class:`TransactionBuilder <stellar_sdk.transaction_builder.TransactionBuilder>`
+object so you can chain multiple calls. But you don't need to call it directly,
+we have prepared a lot of easy-to-use functions for you, such as
+:py:meth:`append_payment_op <stellar_sdk.transaction_builder.TransactionBuilder.append_payment_op>`
+can add a payment operation to the :py:class:`TransactionBuilder <stellar_sdk.transaction_builder.TransactionBuilder>`.
+
+After adding the desired operations, call the :py:meth:`build() <stellar_sdk.transaction_builder.TransactionBuilder.build>`
+method on the :py:class:`TransactionBuilder <stellar_sdk.transaction_builder.TransactionBuilder>`.
+This will return a fully constructed :py:class:`TransactionEnvelope <stellar_sdk.transaction_envelop.TransactionEnvelope>`.
+The transaction object is wrapped in an object called a :py:class:`TransactionEnvelope <stellar_sdk.transaction_envelope.TransactionEnvelope>`,
+the returned transaction will contain
+the sequence number of the source account. This transaction is unsigned.
+You must sign it before it will be accepted by the Stellar network.
+
+.. literalinclude:: ../examples/transaction_builder.py
+   :language: python
+   :linenos:
+
+Sequence Numbers
+----------------
+
+The sequence number of a transaction has to match the sequence number stored by the source account or else the transaction is invalid.
+After the transaction is submitted and applied to the ledger, the source account's sequence number increases by 1.
+
+There are two ways to ensure correct sequence numbers:
+
+
+#. Read the source account's sequence number before submitting a transaction
+#. Manage the sequence number locally
+
+During periods of high transaction throughput, fetching a source account's sequence number from the network may not return
+the correct value. So, if you're submitting many transactions quickly, you will want to keep track of the sequence number locally.
+
+Adding Memos
+------------
+
+Transactions can contain a **memo** field you can use to attach additional information to the transaction. You can do this
+by passing a :py:class:`Memo <stellar_sdk.memo.Memo>` object when you construct the TransactionBuilder.
+
+There are 5 types of memos:
+
+* :py:class:`stellar_sdk.memo.NoneMemo` - empty memo,
+* :py:class:`stellar_sdk.memo.TextMemo`` - 28-byte ascii encoded string memo,
+* :py:class:`stellar_sdk.memo.IdMemo`- 64-bit number memo,
+* :py:class:`stellar_sdk.memo.HashMemo` - 32-byte hash - ex. hash of an item in a content server,
+* :py:class:`stellar_sdk.memo.ReturnHashMemo` - 32-byte hash used for returning payments - contains hash of the transaction being rejected.
+
+.. literalinclude:: ../examples/transaction_builder_with_memo.py
+   :language: python
+   :linenos:
+
+
+Transaction and TransactionEnvelope
+-----------------------------------
+These two concepts may make the novices unclear, but the official has given a good explanation.
+
+Transactions are commands that modify the ledger state. Among other things, Transactions are used to send payments,
+enter orders into the distributed exchange, change settings on accounts, and authorize another account to hold your
+currency. If you think of the ledger as a database, then transactions are SQL commands.
+
+Once a transaction is ready to be signed, the transaction object is wrapped in an object called a Transaction Envelope,
+which contains the transaction as well as a set of signatures. Most transaction envelopes only contain a single
+signature along with the transaction, but in multi-signature setups it can contain many signatures. Ultimately,
+transaction envelopes are passed around the network and are included in transaction sets,
+as opposed to raw Transaction objects.
+

docs/conf.py

@@ -56,8 +56,8 @@
 
 # General information about the project.
 project = 'py-stellar-sdk'
-copyright = '2019, Stellar Community'
-author = 'Stellar Community'
+copyright = '2019, StellarCN and Individual Contributors'
+author = 'StellarCN and Individual Contributors'
 
 import stellar_sdk
 # The version info for the project you're documenting, acts as replacement for
@@ -99,6 +99,8 @@
 # documentation.
 #
 html_theme_options = {
+    'collapse_navigation': False,
+    'style_external_links': False
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

docs/create_account.rst

@@ -0,0 +1,37 @@
+.. _create_account:
+
+
+**************
+Create Account
+**************
+
+Now, in order to create an account, you need to run a :py:class:`CreateAccount
+<stellar_sdk.operation.CreateAccount>` operation with your new account ID.
+Due to `Stellar's account minimums
+<https://www.stellar.org/developers/guides/concepts/fees.html#minimum-account-balance>`_,
+you'll need to transfer the minimum account balance from another account with
+the create account operation. As of this writing, minimum balance is **1 XLM (2
+x 0.5 Base Reserve)**, and is subject to change.
+
+Using The SDF Testnet
+=====================
+If you want to play in the Stellar test network, you can ask our `Friendbot
+<https://www.stellar.org/developers/guides/get-started/create-account.html>`_
+to create an account for you as shown below:
+
+.. literalinclude:: ../examples/create_account_friendbot.py
+   :language: python
+   :linenos:
+
+Using The Stellar Live Network
+==============================
+On the other hand, if you would like to create an account on the live network,
+you should buy some Stellar Lumens from an exchange. When you withdraw the
+Lumens into your new account, the exchange will automatically create the
+account for you. However, if you want to create an account from another
+account of your own, here's an example of how to do so:
+
+
+.. literalinclude:: ../examples/create_account.py
+   :language: python
+   :linenos:

docs/generate_keypair.rst

@@ -0,0 +1,45 @@
+.. _generate_keypair:
+
+
+****************
+Generate Keypair
+****************
+
+:py:class:`Keypair <stellar_sdk.keypair.Keypair>` object represents key pair used to
+sign transactions in Stellar network. :py:class:`Keypair <stellar_sdk.keypair.Keypair>`
+object can contain both a public and private key, or only a public key.
+
+If :py:class:`Keypair <stellar_sdk.keypair.Keypair>` object does not contain private
+key it can't be used to sign transactions. The most convenient method of
+creating new keypair is by passing the account's secret seed:
+
+.. code-block:: python
+   :linenos:
+
+   from stellar_sdk import Keypair
+
+   keypair = Keypair.from_secret("SBK2VIYYSVG76E7VC3QHYARNFLY2EAQXDHRC7BMXBBGIFG74ARPRMNQM")
+   public_key = keypair.public_key()  # GDHMW6QZOL73SHKG2JA3YHXFDHM46SS5ZRWEYF5BCYHX2C5TVO6KZBYL
+   can_sign = keypair.can_sign()  # True
+
+
+You can create a keypair from public key, but its function is limited:
+
+.. code-block:: python
+   :linenos:
+
+   from stellar_sdk import Keypair
+
+   keypair = Keypair.from_public_key("GDHMW6QZOL73SHKG2JA3YHXFDHM46SS5ZRWEYF5BCYHX2C5TVO6KZBYL")
+   can_sign = keypair.can_sign()  # False
+
+You can also create a randomly generated keypair:
+
+.. code-block:: python
+   :linenos:
+
+   from stellar_sdk import Keypair
+
+   keypair = Keypair.random()
+   print("Public Key: " + keypair.public_key())
+   print("Secret Seed: " + keypair.secret())

docs/index.rst

@@ -3,18 +3,68 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to py-stellar-sdk's documentation!
-===========================================
+.. .. include:: ../README.rst
+
+py-stellar-sdk
+===============================
+
+.. image:: https://img.shields.io/travis/StellarCN/py-stellar-base.svg?style=flat-square&maxAge=1800
+    :alt: Travis (.org)
+    :target: https://travis-ci.org/StellarCN/py-stellar-base/
+
+.. image:: https://img.shields.io/readthedocs/stellar-sdk.svg?style=flat-square&maxAge=1800
+    :alt: Read the Docs
+    :target: https://stellar-sdk.readthedocs.io/en/latest/
+
+.. image:: https://img.shields.io/codecov/c/github/StellarCN/py-stellar-base/v2?style=flat-square&maxAge=1800
+    :alt: Codecov
+    :target: https://codecov.io/gh/StellarCN/py-stellar-base
+
+.. image:: https://img.shields.io/codeclimate/maintainability/overcat/py-stellar-sdk?style=flat-square&maxAge=1800
+    :alt: Code Climate maintainability
+    :target: https://codeclimate.com/github/overcat/py-stellar-sdk/maintainability
+
+.. image:: https://img.shields.io/pypi/v/stellar-sdk.svg?style=flat-square&maxAge=1800
+    :alt: PyPI
+    :target: https://pypi.python.org/pypi/stellar-sdk
+
+.. image:: https://img.shields.io/badge/python-3.6%20%7C%203.7-blue?style=flat-square
+    :alt: Python - Version
+    :target: https://pypi.python.org/pypi/stellar-sdk
+
+.. image:: https://img.shields.io/badge/implementation-cpython%20%7C%20pypy-blue?style=flat-square
+    :alt: PyPI - Implementation
+    :target: https://pypi.python.org/pypi/stellar-sdk
+
+
+py-stellar-sdk is a Python library for communicating with
+a `Stellar Horizon server`_. It is used for building Stellar apps on Python. It supports **Python 3.6+** as
+well as PyPy 3.6+.
+
+It provides:
+
+- a networking layer API for Horizon endpoints.
+- facilities for building and signing transactions, for communicating with a Stellar Horizon instance, and for submitting transactions or querying network history.
 
 Quickstart
 ----------
-Here you'll find some basic examples on how to use the library.
+At the absolute basics, you'll want to read up on `Stellar's Documentation
+Guides <https://www.stellar.org/developers/guides/>`_, as it contains a lot of
+information on the concepts used below (Transactions, Payments, Operations,
+KeyPairs, etc.).
 
 .. toctree::
    :maxdepth: 2
 
    install
-   quickstart
+   generate_keypair
+   create_account
+   querying_horizon
+   assets
+   building_transactions
+   payment
+   multi_signature_account
+
 
 API Documentation
 -----------------
@@ -26,15 +76,29 @@ methods.
 
    api
 
-Examples
---------
-Find examples `here`_.
 
+Links
+-----
+* Document: https://stellar-sdk.readthedocs.io
+* Code: https://github.com/StellarCN/py-stellar-base/tree/v2
+* Docker: https://hub.docker.com/r/overcat/py-stellar-base
+* Examples: https://github.com/StellarCN/py-stellar-base/tree/master/examples
+* Issue tracker: https://github.com/StellarCN/py-stellar-base/issues
+* License: `Apache License 2.0 <https://github.com/StellarCN/py-stellar-base/blob/master/LICENSE>`_
+* Releases: https://pypi.org/project/stellar-sdk/
+
+Thanks
+------
+This document is based on `JavaScript Stellar SDK`_ documentation.
+Thank you to all the people who have already contributed to Stellar ecosystem!
 
-Indices
--------
 
-* :ref:`genindex`
+:ref:`genindex`
+---------------
 
 
 .. _here: https://github.com/StellarCN/py-stellar-base/tree/master/examples
+.. _Stellar Horizon server: https://github.com/stellar/go/tree/master/services/horizon
+.. _pip: https://pip.pypa.io/en/stable/quickstart/
+.. _pipenv: https://github.com/pypa/pipenv
+.. _JavaScript Stellar SDK: https://www.stellar.org/developers/js-stellar-sdk/reference/

docs/install.rst

@@ -4,7 +4,7 @@
 Installation
 ************
 
-Via pipenv or pip (Recommended)
+Via pipenv or pip
 ===============================
 
 To install py-stellar-sdk, use pipenv to install the module:
@@ -14,7 +14,7 @@ To install py-stellar-sdk, use pipenv to install the module:
     pipenv install stellar-sdk
 
 If you're not using `pipenv <https://docs.pipenv.org/>`_, you should.
-Otherwise, you can install it via plain old ``pip``. More on installing Python
+Otherwise, you can install it via plain old `pip <https://pip.pypa.io/en/stable/quickstart/>`_. More on installing Python
 and dependencies can be found over in the `Hitchhiker's Guide to Python
 <http://docs.python-guide.org/en/latest/starting/installation/>`_.