Skip to content
This repository was archived by the owner on Jan 13, 2023. It is now read-only.

Commit 9416068

Browse files
lzpaplzpap
authored
Merge pull request #295 from lzpap/release/2.3.0b1
PyOTA v2.3.0-beta1
2 parents 7d0f250 + 2b488df commit 9416068

29 files changed

+1533
-63
lines changed

‎README.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
<h1 align="center">
2+
<br>
3+
<a href="https://docs.iota.org/docs/client-libraries/0.1/getting-started/python-quickstart"><img src="iota-python.png"></a>
4+
</h1>
5+
6+
<h2 align="center">The official Python client library for interacting with the Tangle</h2>
7+
8+
<p align="center">
9+
<a href="https://docs.iota.org/docs/client-libraries/0.1/getting-started/python-quickstart" style="text-decoration:none;">
10+
<img src="https://img.shields.io/badge/Documentation%20portal-blue.svg?style=for-the-badge"
11+
alt="Developer documentation portal">
12+
</p>
13+
<p align="center">
14+
<a href="http://pyota.readthedocs.io/en/latest/?badge=latest" style="text-decoration:none;"><img src="https://img.shields.io/badge/ReadTheDocs-reference-informational.svg" alt="Auto-generated docs"></a>
15+
<a href="https://discord.iota.org/" style="text-decoration:none;"><img src="https://img.shields.io/badge/Discord-9cf.svg?logo=discord" alt="Discord"></a>
16+
<a href="https://iota.stackexchange.com/" style="text-decoration:none;"><img src="https://img.shields.io/badge/StackExchange-9cf.svg?logo=stackexchange" alt="StackExchange"></a>
17+
<a href="https://github.com/iotaledger/entangled/blob/develop/LICENSE" style="text-decoration:none;"><img src="https://img.shields.io/github/license/iotaledger/iota.py.svg" alt="MIT license"></a>
18+
<a href="https://docs.iota.org/docs/node-software/0.1/iri/references/api-reference" style="text-decoration:none;"><img src="https://img.shields.io/badge/Node%20API%20coverage-18/18%20commands-green.svg" alt="Supported IRI API endpoints"></a>
19+
<a href="https://travis-ci.org/iotaledger/iota.py" style="text-decoration:none;"><img src="https://travis-ci.org/iotaledger/iota.py.svg?branch=master" alt="Build status"></a>
20+
</p>
21+
22+
<p align="center">
23+
<a href="#about">About</a> ◈
24+
<a href="#prerequisites">Prerequisites</a> ◈
25+
<a href="#installation">Installation</a> ◈
26+
<a href="#getting-started">Getting started</a> ◈
27+
<a href="#examples">Examples</a> ◈
28+
<a href="#supporting-the-project">Supporting the project</a> ◈
29+
<a href="#joining-the-discussion">Joining the discussion</a>
30+
</p>
31+
32+
---
33+
34+
## About
35+
36+
This is the **official** Python client library, which allows you to do the following:
37+
* Create transactions
38+
* Read transactions
39+
* Sign transactions
40+
* Generate addresses
41+
42+
This is beta software, so there may be performance and stability issues.
43+
Please report any issues in our [issue tracker](https://github.com/iotaledger/iota.py/issues/new).
44+
45+
## Prerequisites
46+
47+
To install the IOTA Python client library and its dependencies, you need Python version 3.7, 3.6, 3.5, or 2.7 installed on your device.
48+
49+
## Installation
50+
51+
To download the IOTA Python client library and its dependencies, do the following:
52+
53+
```bash
54+
pip install pyota
55+
```
56+
57+
### Installing the optional C extension
58+
59+
PyOTA has an optional C extension that improves the performance of its
60+
cryptography features by an average of **60 times**.
61+
62+
To install this extension, do the following:
63+
64+
```bash
65+
pip install pyota[ccurl]
66+
```
67+
68+
### Installing the optional module for local proof of work
69+
70+
To do proof of work on your local device without relying on a node,
71+
you can install the [PyOTA-PoW](https://pypi.org/project/PyOTA-PoW/) extension module.
72+
73+
To install this extension, use the following command::
74+
75+
```bash
76+
pip install pyota[pow]
77+
```
78+
79+
When you've installed this module, you can use it by passing the `local_pow=True` argument to your API instance. Doing so will redirect all `attach_to_tangle`
80+
API calls to an interface function in the `pow` package.
81+
82+
### Installing from source
83+
84+
To install the library from the source code on GitHub, do the following:
85+
86+
```bash
87+
# Recommended, but not required
88+
Create virtualenv
89+
git clone https://github.com/iotaledger/iota.py.git
90+
pip install -e .
91+
```
92+
93+
## Getting started
94+
95+
After you've [installing the library](#installation), you can connect to an IRI node to send transactions to it and interact with the ledger.
96+
An extended guide can be found on our [documentation portal](https://docs.iota.org/docs/client-libraries/0.1/getting-started/python-quickstart), we strongly recommend you to go here for starting off. A quick starting tutorial is shown below.
97+
98+
To connect to a local IRI node, you can do the following:
99+
100+
```py
101+
from iota import Iota
102+
103+
# Create a new instance of the IOTA API object
104+
# Specify which node to connect to
105+
api = Iota(adapter = 'https://nodes.devnet.iota.org:443')
106+
107+
# Call the `get_node_info()` method for information about the node and the Tangle
108+
response = api.get_node_info()
109+
110+
print(response)
111+
```
112+
113+
## Examples
114+
115+
We have a list of test cases in the [`examples` directory](https://github.com/iotaledger/iota.py/tree/master/examples) that you can use as a reference when developing apps with IOTA.
116+
117+
Here's how you could send a zero-value transaction, using the library. For the guide, see the [documentation portal](https://docs.iota.org/docs/client-libraries/0.1/how-to-guides/python/send-your-first-bundle).
118+
119+
```python
120+
# You don't need a seed to send zero-value transactions
121+
api = Iota('https://nodes.devnet.iota.org:443', testnet=True)
122+
123+
# Define a message to send.
124+
# This message must include only ASCII characters.
125+
message = TryteString.from_unicode('Hello world')
126+
127+
# Define an address.
128+
# This does not need to belong to anyone or have IOTA tokens.
129+
# It must only contain a maximum of 81 trytes
130+
# or 90 trytes with a valid checksum
131+
address = 'ZLGVEQ9JUZZWCZXLWVNTHBDX9G9KZTJP9VEERIIFHY9SIQKYBVAHIMLHXPQVE9IXFDDXNHQINXJDRPFDXNYVAPLZAW'
132+
133+
# Define a zero-value transaction object
134+
# that sends the message to the address
135+
tx = ProposedTransaction(
136+
address = Address(address),
137+
message = message,
138+
value = 0
139+
)
140+
141+
# Create a bundle from the `ProposedTransaction` object
142+
# and send the transaction to the node
143+
result = api.send_transfer(transfers=[tx])
144+
145+
print('Bundle: ')
146+
147+
print(result['bundle'].hash)
148+
```
149+
150+
## Supporting the project
151+
152+
If the IOTA Python client library has been useful to you and you feel like contributing, consider posting a [bug report](https://github.com/iotaledger/iota.py/issues/new-issue), feature request or a [pull request](https://github.com/iotaledger/iota.py/pulls/).
153+
We have some [basic contribution guidelines](CONTRIBUTING.rst) to keep our code base stable and consistent.
154+
155+
### Running test cases
156+
157+
To run test, do the following:
158+
159+
```bash
160+
python setup.py test
161+
```
162+
163+
PyOTA is also compatible with [tox](https://tox.readthedocs.io/), which will run the unit tests in different virtual environments (one for each supported version of Python).
164+
165+
To run the unit tests, it is recommended that you use the `-p` argument.
166+
This speeds up the tests by running them in parallel.
167+
168+
Install PyOTA with the `test-runner` extra to set up the necessary
169+
dependencies, and then you can run the tests with the `tox` command::
170+
171+
```bash
172+
pip install -e .[test-runner]
173+
tox -v -p all
174+
```
175+
176+
### Building the auto-generated documentation
177+
178+
The auto-generated documentation can be generated on your local device by doing the following:
179+
180+
```bash
181+
# Install extra dependencies (you only have to do this once)
182+
pip install .[docs-builder]
183+
cd docs
184+
# Build the documentation::
185+
make html
186+
```
187+
188+
## Joining the discussion
189+
190+
If you want to get involved in the community, need help with getting setup, have any issues related with the library or just want to discuss blockchain, distributed ledgers, and IoT with other people, feel free to join our [Discord](https://discord.iota.org/).

‎README.rst‎ renamed to ‎docs/README.rst‎

File renamed without changes.

‎docs/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,6 @@
1212
addresses
1313
multisig
1414
commands
15+
tutorials
1516

16-
.. include:: ../README.rst
17+
.. include:: README.rst

0 commit comments

Comments
 (0)