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
ordatagram
. - 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: - CreateDestError – if failed to create an ephemeral Destination.
- HandshakeError – if handshake failed.
-
-
class
OurDest
(Dest)¶ Internal class returned when calling
Controller.create_dest()
. It inherits methods from theDest
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, useStreamSocket.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, useStreamSocket.parse_headers()
immediately.Returns: a
StreamSocket
instance.Raises: - HandshakeError – if handshake failed.
- AcceptError – if failed to accept connections.
-
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 awith
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.
-
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.
-
-
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.
-
class
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)¶