Class reference

Leaflet defines the following public classes and functions.

Controller and our Destination

class Controller(object)
__init__(self, sam_timeout=60.0, sam_api=('127.0.0.1', 7656), dgram_api=('127.0.0.1', 7655), max_version='3.0')

Make a SAM Controller instance using the given information, and test SAM connection.

check_api(self)

Check SAM API connection. This method will be automatically called when the constructor is called.

Raises:OSError – if failed to connect to SAM API.
lookup(self, name)

Lookup and return the full Destination of the I2P domain name. If name is a Dest instance, return it directly.

Parameters:name (str or Dest) – the .b32.i2p domain name.
Returns:A Dest instance.
Raises:NSError – if lookup failed.
create_dest(self, name = None, style='stream', forward = None, i2cp = None)

Create an ephemeral Destination. The Destination will be destroyed when dereferenced.

Parameters:
  • name (str or None) – a human-readable “nickname” of our Destination, must be unique and cannot contain whitespaces. If the name is not provided, a random name will be generated.
  • style (str) – the Destination type, can be either stream or datagram.
  • forward (int, tuple or None) – for datagram Destinations only. The port number or endpoint which SAM will forward incoming datagram to.
  • i2cp (dict or None) – additional I2CP options.
Returns:

An OurDest instance.
Raises:
class OurDest(Dest)

Internal class returned when calling Controller.create_dest(). It inherits methods from the Dest class. It also defines the following methods.

connect(self, other)

For stream Destinations only.

Ask SAM to connect to a remote I2P peer, and write to the returned wrapped socket object when the connection is successful.

Because of how the SAM protocol is designed, this method simply sends a STREAM CONNECT request to the SAM port. This method will not block. To receive and parse the SAM reply headers, use StreamSocket.parse_headers() immediately.

Parameters:other (str or Dest) – the remote I2P peer to connect to.
Returns:a StreamSocket instance.
Raises:HandshakeError – if handshake failed.
register_accept(self)

For stream Destinations only.

Ask SAM to accept connections to this destination, and write to the returned wrapped socket object when a data stream is available.

Because of how the SAM protocol is designed, this method simply sends a STREAM ACCEPT request to the SAM port. This method will not block. To receive and parse the SAM reply headers, use StreamSocket.parse_headers() immediately.

Returns:

a StreamSocket instance.
Raises:
bind(self)

For datagram Destinations only.

Make a datagram socket, and bind the datagram socket to the endpoint specified in the forward parameter, in the constructor, returning the datagram socket.

Returns:a DatagramSocket instance.
Raises:OSError – when failed to bind to the given endpoint.
close(self)

Close the SAM connection and free resources, destroying the ephemeral Destination.

__enter__(self)
__exit__(self, *args, **kwargs)

Allows you to use Controller.create_dest() inside a with statement suite.

controller = Controller()
with controller.create_dest() as our_dest:
    do_stuff()

Wrapped socket

class WrappedSocket(object)
class StreamSocket(WrappedSocket)

A wrapped socket object that exposes I2P concepts instead of IP concepts. It defines the following methods.

parse_headers(self)

Receive and parse SAM reply headers. This method will block or raise BlockingIOError or raise socket.timeout depending on your socket settings.

When this method is used immediately after OurDest.connect(), the return value and exception type are the following.

Returns:a SAMReply instance.
Raises:ReachError – when the remote peer was unreachable.

When this method is used immediately after OurDest.register_accept(), the return value and exception type are the following.

Returns:a Dest instance, indicating the source of the packet.
Raises:ValueError – if the Destination in the SAM reply headers cannot be parsed.
lookup(self, name)

The alternative to the gethostbyname method.

See Controller.lookup()

close(self)
__enter__(self)
__exit__(self, *args, **kwargs)

Note

It has the following passthru methods.

type  proto  send  recv  sendall  sendfile  fileno  shutdown  detach  makefile  setsockopt  getsockopt  setblocking  settimeout

Notably, the following methods are not available. Calling any of them results in an AttributeError. Instead, their alternatives should be used.

bind()
listen()
accept()
connect()
gethostbyname()
gethostbyname_ex()
class DatagramSocket(WrappedSocket)

A wrapped datagram socket object that exposes I2P concepts instead of IP concepts. It defines the following methods.

class transmit(self, data, [flags, ]dest)

The alternative to the sendto method.

Parameters:
  • data (bytes) – the payload, excluding the SAM datagram header.
  • dest (str or Dest) – where to send the payload to.
Raises:
  • NSError – if naming lookup failed.
  • OSError – if a socket error ocurred.

Note

The maximum acceptable payload size is ~31 KB. However, it is recommended to keep the payload size under 15 KB.

class collect(self, bufsize=32*1024, *args)

The alternative to the recvfrom method.

Parameters:bufsize (int) – the number of bytes you want to receive, excluding the SAM datagram header.
Returns:a (data, address) -> (bytes, Dest) tuple.
Raises:SourceError – if the packet is not forwarded by SAM.

Notably, the following methods are not available. Calling any of them results in an AttributeError. Instead, their alternatives should be used.

sendto()
recvfrom()

SAM data structure

class Dest(object)

A parsed Destination or KeyFile.

Variables:
  • is_private (bool) – True if the Destination contains private keys.
  • base64 (str) – Base-64 representation of the public component of the Destination.
  • base32 (str) – Base-32 representation of the SHA-256 hash of the public component of the Destination.
__init__(self, keyfile, encoding, sig_type = None, private=False)
class SAMReply(object)

Exceptions

class HandshakeError(OSError)
class NSError(OSError)
class CreateDestError(OSError)
class ReachError(OSError)
class AcceptError(OSError)
class SourceError(OSError)