PyOuroboros

 This page is under construction  

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)

$ 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:

from ouroboros.dev import *

On the server side, Accepting a flow:

f = flow_accept()

returns a new allocated flow object.

Client side: Allocating a flow to a certain name:

f = flow_alloc("name")

returns a new allocated Flow object.

Broadcast:

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:

f.dealloc()

To avoid having to call dealloc(), you can also use the with statement:

with flow_alloc("dst") as f:
    f.writeline("line")
    print(f.readline())

After the flow is deallocated, it is not readable or writeable anymore.

f.alloc("name")

will allocate a new flow for an existing Flow object.

To read / write from a flow:

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. Many of these parameters are still highly experimental.

    """
    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
    timeout:      Timeout for the flow to declare the peer dead
    """

For instance,

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.

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:

class FlowProperties(IntFlag):
    ReadOnly
    WriteOnly
    ReadWrite
    Down
    NonBlockingRead
    NonBlockingWrite
    NonBlocking
    NoPartialRead
    NoPartialWrite

See the Ouroboros fccntl documentation for more details.

man fccntl

Event API

Multiple flows can be monitored for activity in parallel using 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:

fset = FlowSet() # create a flow set,
fset.add(f)      # add a Flow 'f' to this set
fset.remove(f)   # remove a Flow 'f' from this set
fset.zero()      # remove all Flows in this set

An FEventQueue stores pending events on flows.

The event types are defined as follows:

class FEventType(IntFlag):
    FlowPkt
    FlowDown
    FlowUp
    FlowAlloc
    FlowDealloc

and can be obtained by calling the next method:

    f, t = fq.next() # Return active flow 'f' and type of event 't'

An FEventQueue is populated from a FlowSet.

fq = FEventQueue()            # Create an eventqueue
fset = FlowSet([f1, f2, f3])   # Create a new set with a couple of Flow objects
fset.wait(fq, timeo=1.0)       # Wait for 1 second or until event
while f, t = fq.next():
    if t == FEventType.FlowPkt:
        msg = f.readline()
    ...
fset.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:

fq = FEventQueue()
with FlowSet([f]) as fset:
    fset.wait(fq)
f2, t = fq.next()
if t == FEventType.FlowPkt:
    line = f2.readline()