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