aboutsummaryrefslogtreecommitdiff
path: root/content/en/docs/API/python.md
diff options
context:
space:
mode:
Diffstat (limited to 'content/en/docs/API/python.md')
-rw-r--r--content/en/docs/API/python.md251
1 files changed, 251 insertions, 0 deletions
diff --git a/content/en/docs/API/python.md b/content/en/docs/API/python.md
new file mode 100644
index 0000000..cb0405c
--- /dev/null
+++ b/content/en/docs/API/python.md
@@ -0,0 +1,251 @@
+---
+title: "Python API for applications"
+author: "Dimitri Staessens"
+description: Python
+date: 2020-05-17
+weight: 20
+draft: false
+description: >
+ Python API
+---
+
+The python API allows you to write Ouroboros-native programs in Python
+(>=3.4) is available as a separate repository. You need Ouroboros
+installed before installing PyOuroboros. To download and install
+PyOuroboros(virtual environment recommended):
+
+```sh
+$ git clone https://ouroboros.rocks/git/pyouroboros
+# Or github mirror:
+# git clone https://github.com/dstaesse/pyouroboros
+$ cd pyouroboros
+./setup.py install
+```
+
+## Basic Usage
+
+import the Ouroboros dev library:
+
+```Python
+from ouroboros.dev import *
+```
+
+On the server side, Accepting a flow:
+
+```Python
+f = flow_accept()
+```
+
+returns a new allocated flow object.
+
+Client side: Allocating a flow to a certain _name_:
+
+```Python
+f = flow_alloc("name")
+```
+returns a new allocated Flow object.
+
+Broadcast:
+
+```Python
+f = flow_join("name")
+```
+
+returns a new allocated Flow object to a broadcast layer.
+
+When a flow is not needed anymore, it can be deallocated:
+
+```Python
+f.dealloc()
+```
+
+To avoid having to call dealloc(), you can also use the with
+statement:
+
+```Python
+with flow_alloc("dst") as f:
+ f.writeline("line")
+ print(f.readline())
+```
+
+After the flow is deallocated, it is not readable or writeable
+anymore.
+
+```Python
+f.alloc("name")
+```
+
+will allocate a new flow for an existing Flow object.
+
+To read / write from a flow:
+
+```Python
+f.read(count) # read up to _count_ bytes and return bytes
+f.readline(count) # read up to _count_ characters as a string
+f.write(buf, count) # write up to _count_ bytes from buffer
+f.writeline(str, count) # write up to _count_ characters from string
+```
+
+## Quality of Service (QoS)
+
+You can specify a QoSSpec for flow allocation.
+```Python
+ """
+ delay: In ms, default 1000s
+ bandwidth: In bits / s, default 0
+ availability: Class of 9s, default 0
+ loss: Packet loss in ppm, default MILLION
+ ber: Bit error rate, errors per billion bits. default BILLION
+ in_order: In-order delivery, enables FRCT, default 0
+ max_gap: Maximum interruption in ms, default MILLION
+ cypher_s: Requested encryption strength in bits
+ """
+```
+
+For instance,
+
+```Python
+qos = QoSSpec(loss=0, cypher_s=256)
+f = flow_alloc("name", qos)
+```
+
+will create a new flow with FRCP retransmission enabled and encrypted
+using a 256-bit ECDHE-AES-SHA3 cypher. The number of encryption
+options will further expand as the prototype matures.
+
+## Manipulating flows
+
+A number of methods are currently available for how to interact with
+Flow. This will further expand as the prototype matures.
+
+```Python
+f.set_snd_timeout(0.5) # set timeout for blocking write
+f.set_rcv_timeout(1.0) # set timeout for blocking read
+f.get_snd_timeout() # get timeout for blocking write
+f.get_rcv_timeout() # get timeout for blocking read
+f.get_qos() # get the QoSSpec for this flow
+f.get_rx_queue_len() # get the number of packets in the rx buffer
+f.get_tx_queue_len() # get the number of packets in the tx buffer
+f.set_flags(flags) # set a number of flags for this flow
+f.get_flags() # get the flags for this flow
+```
+
+The following flags are specified as an enum FlowProperties:
+
+```Python
+class FlowProperties(IntFlag):
+ ReadOnly
+ WriteOnly
+ ReadWrite
+ Down
+ NonBlockingRead
+ NonBlockingWrite
+ NonBlocking
+ NoPartialRead
+ NoPartialWrite
+```
+
+See the Ouroboros fccntl documentation for more details.
+
+```shell
+man fccntl
+```
+
+## Event API
+
+Multiple flows can be monitored for activity in parallel using a
+FlowSet and FEventQueue objects.
+
+FlowSets allow grouping a bunch of Flow objects together to listen for
+activity. It can be constructed with an optional list of Flows, or
+flows can be added or removed using the following methods:
+
+```Python
+set = FlowSet() # create a flow set,
+set.add(f) # add a Flow 'f' to this set
+set.remove(f) # remove a Flow 'f' from this set
+set.zero() # remove all Flows in this set
+```
+
+An FEventQueue stores pending events on flows.
+
+The event types are defined as follows:
+```Python
+class FEventType(IntFlag):
+ FlowPkt
+ FlowDown
+ FlowUp
+ FlowAlloc
+ FlowDealloc
+```
+
+and can be obtained by calling the next method:
+
+```Python
+ f, t = fq.next() # Return active flow 'f' and type of event 't'
+```
+
+An FEventQueue is populated from a FlowSet.
+
+```Python
+fq = FEventQueue() # Create an eventqueue
+set = FlowSet([f1, f2, f3]) # Create a new set with a couple of Flow objects
+set.wait(fq, timeo=1.0) # Wait for 1 second or until event
+while f, t = fq.next():
+ if t == FEventType.FlowPkt:
+ msg = f.readline()
+ ...
+set.destroy()
+```
+
+A flow_set must be destroyed when it goes out of scope.
+To avoid having to call destroy, Python's with statement can be used:
+
+```Python
+fq = FEventQueue()
+with FlowSet([f]) as fs:
+ fs.wait(fq)
+f2, t = fq.next()
+if t == FEventType.FlowPkt:
+ line = f2.readline()
+```
+
+## Examples
+
+Some example code is in the repository's
+[examples](https://ouroboros.rocks/cgit/pyouroboros/tree/examples/) folder.
+
+The following example is a clone of the oecho program in Python. The
+client opens a flow to oecho and sends a brief message. The server
+will echo this message back to the client.
+
+```Python
+from ouroboros.dev import *
+import argparse
+
+
+def client():
+ with flow_alloc("oecho") as f:
+ f.writeline("Hello, PyOuroboros!")
+ print(f.readline())
+
+
+def server():
+ print("Starting the server.")
+ while True:
+ with flow_accept() as f:
+ print("New flow.")
+ line = f.readline()
+ print("Message from client is " + line)
+ f.writeline(line)
+
+
+if __name__ == "__main__":
+ parser = argparse.ArgumentParser(description='A simple echo client/server')
+ parser.add_argument('-l', '--listen', help='run as a server', action='store_true')
+ args = parser.parse_args()
+ server() if args.listen is True else client()
+```
+
+## License
+pyOuorboros is LGPLv2.1. The examples are 3-clause BSD. \ No newline at end of file