aboutsummaryrefslogtreecommitdiff
path: root/content/en
diff options
context:
space:
mode:
authorDimitri Staessens <dimitri@ouroboros.rocks>2020-05-17 20:18:37 +0200
committerDimitri Staessens <dimitri@ouroboros.rocks>2020-05-17 20:18:37 +0200
commitbb49c7108a75f8bdc6f6bc979f0d6c9deecedb78 (patch)
tree90b275f4c2c468170f1c1d3e39b7877a4286fd9d /content/en
parent660fb241e82a4b7bd4b6ba9bcf1966e9f1e62610 (diff)
downloadwebsite-bb49c7108a75f8bdc6f6bc979f0d6c9deecedb78.tar.gz
website-bb49c7108a75f8bdc6f6bc979f0d6c9deecedb78.zip
docs: Add python API description
Diffstat (limited to 'content/en')
-rw-r--r--content/en/docs/API/_index.md10
-rw-r--r--content/en/docs/API/c.md13
-rw-r--r--content/en/docs/API/python.md251
3 files changed, 274 insertions, 0 deletions
diff --git a/content/en/docs/API/_index.md b/content/en/docs/API/_index.md
new file mode 100644
index 0000000..9252a20
--- /dev/null
+++ b/content/en/docs/API/_index.md
@@ -0,0 +1,10 @@
+---
+title: "APIs"
+author: "Dimitri Staessens"
+description: Application Programming Interface
+date: 2020-05-17
+weight: 50
+draft: false
+description: >
+ API
+--- \ No newline at end of file
diff --git a/content/en/docs/API/c.md b/content/en/docs/API/c.md
new file mode 100644
index 0000000..21cb250
--- /dev/null
+++ b/content/en/docs/API/c.md
@@ -0,0 +1,13 @@
+---
+title: "C API for applications"
+author: "Dimitri Staessens"
+description: Python
+date: 2020-05-17
+weight: 10
+draft: false
+description: >
+ C API
+---
+
+The C API is currently detailed in the
+[man pages](https://ouroboros.rocks/man/man3/flow_alloc.3.html) \ No newline at end of file
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