API Reference

PlatformAPI

class pipes.PlatformAPI(path, logTag=None, tester=False)

Global manager for the Pipes API. This must be created to access API calls, and only one instance may exist in a process. Pass the filesystem path where the Pipes API data is managed. Start with an empty path if initializing for the first time. Provides top-level access to Networks and Identities configured at the initialization path.

property version

Returns a string describing the Pipes API version.

shutdown()

Cleanly shut down the API and close all associated resources.

networks()

Returns the list of Networks accessible by the API.

bootstrapNetwork()

Returns the bootstrap Network, used to get metadata about other available Networks.

networkWithId(networkId)

Obtains a Network object by its networkId.

addNetwork(path)

Adds a new Network with the “netfile” at the indiciated path. This must be a valid netfile created with the Network administration tools.

hasLocalIdentity()

Returns True if the API has an Identity configured.

localIdentity()

Returns the single local identity if one is configured.

identityWithId(identityId)

Returns the Identity with the given id.

identities()

Returns a list of all configured Identities.

addIdentity(name, keyBits=None)

Creates a new Identity with the indicated name, and returns it.

nodes()

Returns the list of Nodes currently managed by the API.

nodeWithId(nodeId)

Obtains a Node object by its nodeId.

addNode(network, identity, location)

Creates a new Node using the indicated network, identity, and location string.

Network

class pipes.Network

Represents a Network which can be connected to by the Pipes API.

property name

The name of the Network.

property networkId

The identifier of the Network. This is a bytes object.

isBootstrap()

Indicates whether this is a bootstrap network; if so, a connected Node can only be used to obtain the list of available Networks.

hasSecret()

Returns True if the Pipes API has the secret required to join this Network.

setSecret(secret)

Use this to set the secret for this Network, which is required before connection. Returns True if the secret was correct for the Network.

addGateway(host, port)

Adds a Gateway Peer to this Network, given by the indicated host and port. A Node will attempt to connect to the Network via all known Gateways.

gateways()

Returns the list of Gateways currently configured for this Network.

Gateway

class pipes.Gateway

A host/port combo used to connect to a Network.

property network

The Network this Gateway is associated with.

property networkId

The Network ID this Gateway is associated with.

property host

The Gateway host.

property port

The Gateway port.

Identity

class pipes.Identity

Represents an Identity in the Pipes API.

property identityId

The identifier of the Identity. This is a bytes object.

property name

The name of the Identity (node name on the network).

Node

class pipes.Node

Represents a Node that is connected to a Pipes Network.

property nodeId

The identifier of the Node. This is a bytes object.

property network

The Network to which this Node is attached.

property identity

The Identity used for this Node.

start()

Used to start this Node. The Node will attempt to connect to any/all configured Gateways, and start listening for incoming connections (if configured).

shutdown()

Used to disconnect the Node and cleanup all associated resources.

isActive()

Returns True if this Node has been started.

isConnected()

Returns True if this Node is connected to any peers on the network.

connectedPeers()

Returns a list of the direct peers to which this Node is connected.

connectedNodes()

Returns a list of all Nodes currently connected to the Network.

nodeWithId(partialNodeId)

Returns the metadata for the Node on the network with the indicated nodeId (or partial nodeId prefix).

knownNodes()

Returns the list of all Nodes that have ever connected to this Network.

pipelines()

Returns the list of Pipelines available on this Network.

createPipeline(name, toNodeId=None, persistent=False, live=False, encrypted=False, ephemeral=False, realtime=False, unsalted=False, salt=None)

Requests creation of a new Pipeline on the Network, with the indicated parameters. Returns the pipelineId of the new Pipeline; the Node listener will be notified of the new Pipeline when it becomes available.

bootstrapNetworks()

Returns a list of the bootstrap Networks. Only available if this Node is attached to a bootstrap Network.

addBootstrapNetwork(networkId)

Adds a new network to the bootstrap list. Only available if this Node is attached to a bootstrap Network.

addListener(listener)

Used to add a listener Node events, see the NodeListener class for optional methods to implement to receive update notifications.

removeListener(listener)

Remove the indicated listener from this pipeline’s listeners.

NodeListener

class pipes.NodeListener

Interface object used to handle Node notifications.

handleConnectionUpdate(isConnected, node)

Used to notify when the Node’s connections status changes.

handleNodeStatusUpdate(peerNodeRef, myNode)

Used to notify when the Node’s status changes; typically this means some other Node has joined/left the network.

handlePipeline(pipeline, node)

Used to listen for when a new Pipeline is available on this Node.

NodeRef

class pipes.NodeRef

A reference to another Node on the Network.

property nodeId

The Node’s identifier.

property name

The name of the Identity for this Node.

property location

The Node’s location.

property version

The version of the software running on the Node.

isConnected()

Returns True if the indicated Node currently appears to be connected to the network.

isPeer()

Returns True if the indicated Node currently has a direct connection to the local Node.

Pipeline

class pipes.Pipeline

property pipelineId

The identifier of the Pipeline. This is a bytes object.

property name

The name of the Pipeline.

property encrypted

Returns True if this is an encrypted Pipeline.

isPointToPoint()

Returns True if this is a point-to-point Pipeline.

property otherPointToPointNode

If this is a point-to-point Pipeline, returns the nodeId of the other Node.

property persistent

Returns True if this is a persistent Pipeline.

property live

Returns True if this is a live (non-persistent) Pipeline.

property realtime

Applicable to live pipelines only (realtime pipelines use UDP transport).

shutdown()

Only applies to ephemeral pipelines; removes the Pipeline from the Network and releases associated resources.

nodesWithEncryptionSecret()

Returns the list of nodeId’s of Nodes that have this secret.

putPacket(data, packetType=None, destinationNodeId=None)

Used to put a new Packet on this Pipeline. Argument must be data (bytes). May indicate an integer packetType, if desired. If destinationNodeId is specified, the packet will only be delivered to the indicated Node (only available on live pipelines).

packetWithId(packetId)

Used to obtain the data the indicated Packet. Only available on persistent Pipelines.

getPacketsSince(packetLogId=- 1)

Used to obtain all Packets since the indicated packetLogId; if omitted, then obtains all Packets on this Pipeline. Packets are returned in order.

putFilePacket(path)

Used to put a new Packet on this Pipeline, using the contents of the file and the indicated path. Returns the packetId of the sent Packet.

isSynchronizing()

Returns True if this pipeline is actively synchronizing data. Applies to persistent Pipelines only.

setupUDPPortMap(host=None, port=0)

Maps this pipeline to a local UDP port. All data received on the pipeline is routed to the indicated port, and all data received on the port is sent to the pipeline. Only supported for realtime point-to-point pipelines. By default listens on 127.0.0.1 and picks an unused ephemeral port. Specify host to listen on a specific IP (or 0.0.0.0 to listen on any IP), and specify port if you want to use a particular port. When the portmap is ready, the handleUDPPortMap() method on listeners will be invoked.

property udpHost

If a UDP port map is configured on this pipeline, the returns the IP address on which the port is listening.

property udpPort

If a UDP port map is configured on this pipeline, the returns the UDP port to which the pipeline is mapped.

addListener(listener)

Used to add a listener Pipeline events, see the PipelineListener class for optional methods to implement to receive update notifications.

removeListener(listener)

Remove the indicated listener from this pipeline’s listeners.

PipelineListener

class pipes.PipelineListener

Interface object used to handle Pipeline notifications.

handlePacket(packet, pipeline)

Used to listen for when a new Packet is available on this Pipeline.

handleStatusUpdate(pipeline)

Used to notify when the Pipeline’s status changes (isReady(), isClosed()).

handleUDPPortMap(pipeline)

Used to notify when the Pipeline’s UDP port map is ready.

handleSyncUpdate(isSynchronized, pipeline)

Used to listen for when the Pipeline begins or finishes synchronizing. Only applies to persistent Pipelines.

Packet

class pipes.Packet

property packetId

The identifier of the Packet. This is a bytes object.

property packetType

An integer type identifier for this packet.

property size

The size the Packet (in bytes).

property logId

For Packets on a persistent Pipeline, the integer log identifier of the Packet. These will always be delivered in strictly increasing order, starting with 0.

property data

The Packet data (bytes).

writeDataToPath(path)

Used to write the Packet data to the indicated filesystem path, useful for large Packets.