README.md 4.37 KB
Newer Older
Moul's avatar
Moul committed
1
2
# DuniterPy
Most complete client oriented Python library for [Duniter](https://git.duniter.org/nodes/typescript/duniter)/Ğ1 ecosystem.
Moul's avatar
Moul committed
3

Moul's avatar
Moul committed
4
This library was originally developed for [Sakia](https://git.duniter.org/clients/python/sakia) desktop client which is now discontinued.
Moul's avatar
Moul committed
5
It is currently used by following programs:
Moul's avatar
Moul committed
6
- [Tikka](https://git.duniter.org/clients/python/tikka), the desktop client.
Moul's avatar
Moul committed
7
8
9
- [Silkaj](https://silkaj.duniter.org/), command line client.
- [Jaklis](https://git.p2p.legal/axiom-team/jaklis), command line client for Cs+/Gchange pods.
- [Ğ1Dons](https://git.duniter.org/matograine/g1pourboire), Ğ1Dons, paper-wallet generator aimed at giving tips in Ğ1.
Moul's avatar
Moul committed
10
11

## Features
Moul's avatar
Moul committed
12
13
14
15
16
17
18
19
20
21
22
23
24
25
### Network
- APIs support: BMA, GVA, WS2P, and CS+:
  - [Basic Merkle API](https://git.duniter.org/nodes/typescript/duniter/-/blob/dev/doc/HTTP_API.md), first Duniter API to be deprecated
  - GraphQL Verification API, Duniter API in developement meant to replace BMA. Based on GraphQL.
  - Websocket to Peer, Duniter inter-nodes (servers) API
  - Cesium+, non-Duniter API, used to store profile data related to the blockchain as well as ads for Cesium and Ğchange.
- Non-threaded asynchronous/synchronous connections
- Support HTTP, HTTPS, and WebSocket transport for the APIs
- Endpoints management

### Blockchain
- Support [Duniter blockchain protocol](https://git.duniter.org/documents/rfcs#duniter-blockchain-protocol-dubp)
- Duniter documents management: transaction, block and WoT documents
- Multiple authentication methods
Moul's avatar
Moul committed
26
- Duniter signing key
Moul's avatar
Moul committed
27
- Sign/verify and encrypt/decrypt messages with Duniter credentials
Moul's avatar
Moul committed
28
29

## Requirements
Moul's avatar
Moul committed
30
- Python >= 3.7.0
31
- [websocket-client](https://pypi.org/project/websocket-client)
Moul's avatar
Moul committed
32
33
34
35
36
37
- [jsonschema](https://pypi.org/project/jsonschema)
- [pyPEG2](https://pypi.org/project/pyPEG2)
- [attrs](https://pypi.org/project/attrs)
- [base58](https://pypi.org/project/base58)
- [libnacl](https://pypi.org/project/libnacl)
- [pyaes](https://pypi.org/project/pyaes)
Moul's avatar
Moul committed
38
39

## Installation
40
41
42
43
44
45
You will require following dependencies:
```bash
sudo apt install python3-pip python3-dev python3-wheel libsodium23
```

You can install DuniterPy and its dependencies with following command:
Moul's avatar
Moul committed
46
```bash
47
pip3 install duniterpy --user
Moul's avatar
Moul committed
48
49
```

50
## Install the development environment
Moul's avatar
Moul committed
51
- [Install Poetry](https://python-poetry.org/docs/#installation)
52

Moul's avatar
Moul committed
53
## Documentation
Moul's avatar
Moul committed
54
[Online official automaticaly generated documentation](https://clients.duniter.io/python/duniterpy/index.html)
Moul's avatar
Moul committed
55

56
## Examples
57
The [examples folder](https://git.duniter.org/clients/python/duniterpy/tree/master/examples) contains scripts to help you!
Moul's avatar
Moul committed
58

59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
- Have a look at the `examples` folder
- Run examples from parent folder directly
```bash
poetry run python examples/request_data.py
```

Or from Python interpreter:
```bash
poetry run python
>>> import examples
>>> help(examples)
>>> examples.create_public_key()
```

`request_data_async` example requires to be run with `asyncio`:
```bash
>>> import examples, asyncio
>>> asyncio.get_event_loop().run_until_complete(examples.request_data_async())
```

Moul's avatar
Moul committed
79
### How to generate and read locally the autodoc
Moul's avatar
Moul committed
80

Moul's avatar
Moul committed
81
- Install Sphinx, included into the development dependencies:
Moul's avatar
Moul committed
82
```bash
Moul's avatar
Moul committed
83
poetry install
Moul's avatar
Moul committed
84
85
```

86
- Generate HTML documentation in `public` directory:
Moul's avatar
Moul committed
87
```bash
88
make docs
Moul's avatar
Moul committed
89
90
91
92
```

## Development
* When writing docstrings, use the reStructuredText format recommended by https://www.python.org/dev/peps/pep-0287/#docstring-significant-features
93
* Use `make check` commands to check the code and the format.
Moul's avatar
Moul committed
94

95
* Install runtime dependencies
Moul's avatar
Moul committed
96
```bash
97
poetry install --no-dev
Moul's avatar
Moul committed
98
99
```

100
* Before submitting a merge requests, please check the static typing and tests.
Moul's avatar
Moul committed
101
102
103

* Install dev dependencies
```bash
104
poetry install
Moul's avatar
Moul committed
105
106
107
108
```

* Check static typing with [mypy](http://mypy-lang.org/)
```bash
109
make mypy
Moul's avatar
Moul committed
110
111
112
```

## Packaging and deploy
Moul's avatar
Moul committed
113
### PyPI
Moul's avatar
Moul committed
114
115
116
117
118
Change and commit and tag the new version number (semantic version number)
```bash
./release.sh 0.42.3
```

Moul's avatar
Moul committed
119
Build the PyPI package in the `dist` folder
Moul's avatar
Moul committed
120
```bash
121
make build
Moul's avatar
Moul committed
122
123
```

124
Deploy the package to PyPI test repository:
Moul's avatar
Moul committed
125
```bash
126
make deploy_test
Moul's avatar
Moul committed
127
128
```

Moul's avatar
Moul committed
129
Install the package from PyPI test repository
Moul's avatar
Moul committed
130
131
132
133
```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.python.org/simple/ duniterpy
```

134
Deploy the package on the PyPI repository:
Moul's avatar
Moul committed
135
```bash
136
make deploy
Moul's avatar
Moul committed
137
```
138
139
140

## Packaging status
[![Packaging status](https://repology.org/badge/vertical-allrepos/python:duniterpy.svg)](https://repology.org/project/python:duniterpy/versions)