greenhouse.io – Cooperative I/O Drop-Ins¶

class greenhouse.io.sockets.Socket(*args, **kwargs)¶

a replacement class for the standard library’s socket.socket

greenhouse.Sockets wrap the standard library’s sockets, using the underlying socket in a non-blocking way and blocking the current coroutine where appropriate.

They provide a totally matching API, however

accept()¶

accept a connection on the host/port to which the socket is bound

Note

if there is no connection attempt already queued, this method will block until a connection is made

Returns:	a two-tuple of (socket, address) where the socket is connected, and the address is the (ip_address, port) of the remote end

bind(address)¶

set the socket to operate on an address

Parameters:	address – the address on which the socket will operate. the format of this argument depends on the socket’s type; for TCP sockets, this is a (host, port) two-tuple

close()¶

close the current connection on the socket

After this point all operations attempted on this socket will fail, and once any queued data is flushed, the remote end will not receive any more data

connect(address)¶

initiate a new connection to a remote socket bound to an address

Note

this method will block until the connection has been made

Parameters:	address – the address to which to initiate a connection, the format of which depends on the socket’s type; for TCP sockets, this is a (host, port) two-tuple

connect_ex(address)¶

initiate a connection without blocking

Parameters:	address – the address to which to initiate a connection, the format of which depends on the socket’s type; for TCP sockets, this is a (host, port) two-tuple
Returns:	the error code for the connection attempt – 0 indicates success

dup()¶

create a new copy of the current socket on the same file descriptor

Returns:	a new Socket

fileno()¶

get the file descriptor

Returns:	the integer file descriptor of the socket

getpeername()¶

address information for the remote end of a connection

Returns:	a representation of the address at the remote end of the connection, the format depends on the socket’s type

getsockname()¶

address information for the local end of a connection

Returns:	a representation of the address at the local end of the connection, the format depends on the socket’s type

getsockopt(level, optname, *args, **kwargs)¶

get the value of a given socket option

the values for level and optname will usually come from constants in the standard library socket module. consult the unix manpage getsockopt(2) for more information.

Parameters:	level (int) – the level of the requested socket option optname (int) – the specific socket option requested buflen (int) – the length of the buffer to use to collect the raw value of the socket option. if provided, the buffer is returned as a string and it is not parsed.
Returns:	a string of the socket option’s value

gettimeout()¶

get the timeout set for this specific socket

Returns:	the number of seconds the socket’s blocking operations should block before raising a socket.timeout in a float value

listen(backlog)¶

listen for connections made to the socket

Parameters:	backlog (int) – the queue length for connections that haven’t yet been accept()ed

makefile(mode='r', bufsize=-1)¶

create a file-like object that wraps the socket

Parameters:	mode (str) – like the mode argument for other files, indicates read 'r', write 'w', or both 'r+' (default 'r') bufsize (int) – the length of the read buffer to use. 0 means unbuffered, < 0 means use the system default (default -1)
Returns:	a file-like object for which reading and writing sends and receives data over the socket connection

recv(bufsize, flags=0)¶

receive data from the connection

Note

this method will block until data is available to be read

see the unix manpage for recv(2) for more information

Parameters:	bufsize (int) – the maximum number of bytes to receive. fewer may be returned, however flags (int) – flags for the receive call. consult the unix manpage for recv(2) for what flags are available
Returns:	the data it read from the socket connection

recv_into(buffer, bufsize=0, flags=0)¶

receive data from the connection and place it into a buffer

Note

this method will block until data is available to be read

Parameters:	buffer – a sized buffer object to receive the data (this is generally an array.array('c', ...) instance) bufsize (int) – the maximum number of bytes to receive. fewer may be returned, however. defaults to the size available in the provided buffer. flags (int) – flags for the receive call. consult the unix manpage for recv(2) for what flags are available
Returns:	the number of bytes received and placed in the buffer

recvfrom(bufsize, flags=0)¶

receive data on a socket that isn’t necessarily a 1-1 connection

Note

this method will block until data is available to be read

Parameters:	bufsize (int) – the maximum number of bytes to receive. fewer may be returned, however flags (int) – flags for the receive call. consult the unix manpage for recv(2) for what flags are available
Returns:	a two-tuple of (data, address) – the string data received and the address from which it was received

recvfrom_into(buffer, bufsize=0, flags=0)¶

receive data on a non-TCP socket and place it in a buffer

Note

this method will block until data is available to be read

Parameters:	buffer – a sized buffer object to receive the data (this is generally an array.array('c', ...) instance) bufsize (int) – the maximum number of bytes to receive. fewer may be returned, however. defaults to the size available in the provided buffer. flags (int) – flags for the receive call. consult the unix manpage for recv(2) for what flags are available
Returns:	a two-tuple of (bytes, address) – the number of bytes received and placed in the buffer, and the address it was received from

send(data, flags=0)¶

send data over the socket connection

Note

this method may block if the socket’s send buffer is full

Parameters:	data (str) – the data to send flags (int) – flags for the send call. this has the same meaning as for recv()
Returns:	the number of bytes successfully sent, which may not necessarily be all the provided data

sendall(data, flags=0)¶

send data over the connection, and keep sending until it all goes

Note

this method may block if the socket’s send buffer is full

Parameters:	data (str) – the data to send flags (int) – flags for the send call. this has the same meaning as for recv()

sendto(data, *args)¶

send data to a particular address

Note

this method may block if the socket’s send buffer is full

Parameters:	data (str) – the data to send flags (int) – flags for the send call. this has the same meaning as for recv(). defaults to 0 address – a representation of the address to which to send the data, the format depends on the socket’s type

setblocking(flag)¶

modify the behavior of blocking methods on the socket

greenhouse sockets already setblocking(False) on the underlying standard python socket, but modifying this flag will affect the behavior of sockets either blocking the current coroutine or not.

if this blocking is turned off, then blocking methods (such as recv()) will raise the relevant exception when they would otherwise block the coroutine.

Parameters:	flag (bool) – whether to enable or disable blocking

setsockopt(level, optname, value)¶

set the value of a given socket option

the values for level and optname will usually come from constants in the standard library socket module. consult the unix manpage setsockopt(2) for more information.

Parameters:	level (int) – the level of the set socket option optname (int) – the specific socket option to set value (int) – the value to set for the option

settimeout(timeout)¶

set the timeout for this specific socket

Parameters:	timeout (float or None) – the number of seconds the socket’s blocking operations should block before raising a socket.timeout

shutdown(how)¶

close one or both ends of the connection

Parameters:	how – the end(s) of the connection to shutdown. valid values are socket.SHUT_RD, socket.SHUT_WR, and socket.SHUT_RW for shutting down the read end, the write end, or both respectively

class greenhouse.io.files.File(name, mode='rb')¶

the greenhouse drop-in replacement for the built-in file type

this class will use non-blocking file descriptors for its IO, so that whatever readystate information the OS and filesystem provide will be used to block only a single coroutine rather than the whole process. unfortunately filesystems tend to be very unreliable in this regard.

close()¶

close the file, and its underlying descriptor

fileno()¶

get the file descriptor integer

flush()¶

flush buffered writes to disk immediately

this is provided for compatibility – this class does no write buffering itself, so it is a no-op

classmethod fromfd(fd, mode='rb', bufsize=-1)¶

create a cooperating greenhouse file from an existing descriptor

Parameters:	fd (int) – the file descriptor to wrap in a new file object mode (str) – the file mode bufsize – the size of read buffer to use. 0 indicates unbuffered, and < 0 means use the system default. defaults to -1
Returns:	a new File object connected to the descriptor

isatty()¶

return whether the file is connected to a tty or not

read(size=-1)¶

read a number of bytes from the file and return it as a string

Note

this method will block if there is no data already available

Parameters:	size (int) – the maximum number of bytes to read from the file. < 0 means read the file to the end
Returns:	a string of the read file contents

readline(max_len=-1)¶

read from the file until a newline is encountered

Note

this method will block if there isn’t already a full line available from the data source

Parameters:	max_len (int) – stop reading a single line after this many bytes
Returns:	a string of the line it read from the file, including the newline at the end

readlines(bufsize=-1)¶

reads the entire file, producing the lines one at a time

Note

this method will block until the data source is exhausted

Parameters:	bufsize (int) – the read buffer size to use
Returns:	a list of all the lines in the file to the end

seek(position, modifier=0)¶

move the cursor on the file descriptor to a different location

Parameters:	position (int) – an integer offset from the location indicated by the modifier modifier – an indicator of how to find the seek location. os.SEEK_SET means start from the beginning of the file os.SEEK_CUR means start wherever the cursor already is os.SEEK_END means start from the end of the file the default is os.SEEK_SET

tell()¶

get the file descriptor’s position relative to the file’s beginning

write(data)¶

write data to the file

Parameters:	data (str) – the data to write into the file, at the descriptor’s current position

writelines(lines)¶

write a sequence of strings into the file

writelines() does not add newlines to the strings

Parameters:	lines (iterable) – a sequence of strings to write to the file

greenhouse.io.files.stdin = <greenhouse.io.files._StdIOFile object at 0x1a7bad0>¶

a non-blocking file object for cooperative stdin reading

greenhouse.io.files.stdout = <greenhouse.io.files._StdIOFile object at 0x1a7bbd0>¶

a non-blocking file object for cooperative stdout writing

greenhouse.io.files.stderr = <greenhouse.io.files._StdIOFile object at 0x1a7bc90>¶

a non-blocking file object for cooperative stderr writing

greenhouse.io.descriptor.wait_fds(fd_events, inmask=1, outmask=2, timeout=None)¶

wait for the first of a number of file descriptors to have activity

Note

this method can block

it will return once there is relevant activity on the file descriptors, or the timeout expires

Parameters:	fd_events (list) – two-tuples, each one a file descriptor and a mask made up of the inmask and/or the outmask bitwise-ORd together inmask (int) – the mask to use for readable events (default 1) outmask (int) – the mask to use for writable events (default 2) timeout (int, float or None) – the maximum time to wait before raising an exception (default None)
Returns:	a list of two-tuples, each is a file descriptor and an event mask (made up of inmask and/or outmask bitwise-ORd together) representing readable and writable events

greenhouse.io.ipc.pipe()¶

create an inter-process communication pipe

Returns:	a pair of File objects (read, write) for the two ends of the pipe