-
Notifications
You must be signed in to change notification settings - Fork 3
/
README.md.pynng
125 lines (92 loc) · 4.03 KB
/
README.md.pynng
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
This is pynng.
==============
[](https://github.com/codypiersall/pynng/blob/master/LICENSE.txt)
[](https://pypi.org/project/pynng)
[](https://github.com/codypiersall/pynng/actions)
[](https://github.com/codypiersall/pynng/actions)
[](https://pynng.readthedocs.io)
Ergonomic bindings for [nanomsg next generation] \(nng), in Python.
pynng provides a nice interface on top of the full power of nng. nng, and
therefore pynng, make it easy to communicate between processes on a single
computer or computers across a network. This library is compatible with Python
≥ 3.5. nng is the [rewriting](https://nanomsg.github.io/nng/RATIONALE.html) of
[Nanomsg](https://nanomsg.org/), which is the spiritual successor to [ZeroMQ](http://zeromq.org/).
Goals
-----
Provide a Pythonic, works-out-of-the box library on Windows and Unix-y
platforms. Like nng itself, the license is MIT, so it can be used without
restriction.
Installation
------------
On Windows, MacOS, and Linux, the usual
pip3 install pynng
should suffice. Note that on 32-bit Linux and on macOS no binary distributions
are available, so [CMake](https://cmake.org/) is also required.
Building from the GitHub repo works as well, natch:
git clone https://github.com/codypiersall/pynng
cd pynng
pip3 install -e .
(If you want to run tests, you also need to `pip3 install trio curio pytest pytest-asyncio pytest-trio pytest-curio`,
then just run `pytest test`.)
pynng might work on the BSDs as well. Who knows!
Using pynng
-----------
Using pynng is easy peasy:
```python
from pynng import Pair0
s1 = Pair0()
s1.listen('tcp://127.0.0.1:54321')
s2 = Pair0()
s2.dial('tcp://127.0.0.1:54321')
s1.send(b'Well hello there')
print(s2.recv())
s1.close()
s2.close()
```
Since pynng sockets support setting most parameters in the socket's `__init__`
method and is a context manager, the above code can be written much shorter:
```python
from pynng import Pair0
with Pair0(listen='tcp://127.0.0.1:54321') as s1, \
Pair0(dial='tcp://127.0.0.1:54321') as s2:
s1.send(b'Well hello there')
print(s2.recv())
```
### Using pynng with an async framework
Asynchronous sending also works with
[curio](https://github.com/dabeaz/curio), [trio](https://trio.readthedocs.io/en/latest/) and
[asyncio](https://docs.python.org/3/library/asyncio.html). Here is an example
using trio:
```python
import pynng
import trio
async def send_and_recv(sender, receiver, message):
await sender.asend(message)
return await receiver.arecv()
with pynng.Pair0(listen='tcp://127.0.0.1:54321') as s1, \
pynng.Pair0(dial='tcp://127.0.0.1:54321') as s2:
received = trio.run(send_and_recv, s1, s2, b'hello there old pal!')
assert received == b'hello there old pal!'
```
Many other protocols are available as well:
* `Pair0`: one-to-one, bidirectional communication.
* `Pair1`: one-to-one, bidirectional communication, but also supporting
polyamorous sockets
* `Pub0`, `Sub0`: publish/subscribe sockets.
* `Surveyor0`, `Respondent0`: Broadcast a survey to respondents, e.g. to find
out what services are available.
* `Req0`, `Rep0`: request/response pattern.
* `Push0`, `Pull0`: Aggregate messages from multiple sources and load balance
among many destinations.
Examples
--------
Some examples (okay, just two examples) are available in the
[examples](https://github.com/codypiersall/pynng/tree/master/examples)
directory.
Git Branch Policy
-----------------
The **only** stable branch is `master`. There will *never* be a `git push -f`
on master. On the other hand, all other branches are not considered stable;
they may be deleted, rebased, force-pushed, and any other manner of funky
business.
[nanomsg next generation]: https://nanomsg.github.io/nng/index.html