Section 20.1. The socket Module

20.1. The socket Module

The socket module supplies a factory function, also named socket, that you call to generate a socket object s. To perform network operations, call methods on s. In a client program, connect to a server by calling s.connect. In a server program, wait for clients to connect by calling s.bind and s.listen. When a client requests a connection, accept the request by calling s.accept, which returns another socket object s1 connected to the client. Once you have a connected socket object, transmit data by calling its method send and receive data by calling its method recv.

Python supports both current Internet Protocol (IP) standards. IPv4 is more widespread; IPv6 is newer. In IPv4, a network address is a pair (host,port). host is a Domain Name System (DNS) hostname such as 'www.python.org' or a dotted-quad IP address such as '194.109.137.226'. port is an integer that indicates a socket's port number. In IPv6, a network address is a tuple (host,port,flowinfo,scopeid). IPv6 infrastructure is not yet widely deployed; I do not cover IPv6 further in this book. When host is a DNS hostname, Python looks up the name on your platform's DNS infrastructure, using the IP address that corresponds to the name.

Module socket supplies an exception class error. Functions and methods of socket raise error to diagnose socket-specific errors. Module socket also supplies many functions. Many of these functions translate data, such as integers, between your host's native format and network standard format. The higher-level protocol that your program and its counterpart are using on a socket determines what conversions you must perform.

20.1.1. socket Functions

The most frequently used functions of module socket are as follows.

getdefault-timeout	geTDefaulttimeout( ) Returns a float that is the timeout (in seconds, possibly with a fractional part) currently set by default on newly created socket objects, or None if newly created socket objects currently have no timeout behavior.
getfqdn	getfqdn(host='') Returns the fully qualified domain name string for the given host (a string that is most often a domain name that is not fully qualified). When host is '', returns the fully qualified domain name string for the local host.
gethostbyaddr	gethostbyaddr(ipaddr) Returns a tuple with three items (hostname,alias_list,ipaddr_list). hostname is a string, the primary name of the host whose IP address you pass as string ipaddr. alias_list is a list of zero or more alias names for the host. ipaddr_list is a list of one or more dotted-quad addresses for the host.
gethostby-name_ex	gethostbyname_ex(hostname) Returns the same results as gethostbyaddr, but takes as an argument a hostname string that can be either an IP dotted-quad address or a DNS name.
htonl	htonl(i32) Converts the 32-bit integer i32 from this host's format into network format.
htons	htons(i16) Converts the 16-bit integer i16 from this host's format into network format.
inet_aton	inet_aton(ipaddr_string) Converts the IP address ipaddr_string to 32-bit network format; returns a 4-byte string.
inet_ntoa	inet_ntoa(packed_string) Converts the 4-byte network-format string packed_string; returns IP dotted-quad string.
ntohl	ntohl(i32) Converts the 32-bit integer i32 from network format into this host's format; returns int.
ntohs	ntohs(i16) Converts the 16-bit integer i16 from network format into this host's format; returns int.
setdefault-timeout	setdefaulttimeout(t) Sets float t as the timeout (in seconds, possibly with a fractional part) set by default on newly created socket objects. If t is None, sets newly created socket objects to have no timeout behavior.
socket	socket(family,type) Creates and returns a socket object with the given family and type. family is usually attribute AF_INET of module socket, indicating you want an Internet (TCP/IP) kind of socket. Depending on your platform, family may also be another attribute of module socket. AF_UNIX, on Unix-like platforms only, indicates that you want a Unix-like socket. (This book does not cover non-Internet sockets, since it focuses on cross-platform Python.) type is one of a few attributes of module socketusually SOCK_STREAM for a TCP (connection) socket, or SOCK_DGRAM for a UDP (datagram) socket.

20.1.2. The socket Class

A socket object s supplies many methods. The commonly used ones are as follows.

accept	s.accept( ) Accepts a connection request and returns a pair (s1,(ipaddr,port)). s1 is a new connected socket; ipaddr and port are the IP address and port number of the counterpart. s must be SOCK_STREAM; you must have previously called s.bind and s.listen. If no client is trying to connect, accept blocks until some client tries to connect.
bind	s.bind((host,port)) Binds socket s to accept connections from host host on port number port. host can be the empty string '' to accept connections from any host. It's an error to call s.bind twice on any socket object s.
close	s.close( ) Closes the socket, terminating any listening or connection on it. It's an error to call any other method on s after s.close.
connect	s.connect((host,port)) Connects socket s to the server on the given host and port. Blocks until the server accepts or rejects the connection attempt, and raises an exception in case of errors.
getpeername	s.getpeername( ) Returns a pair (ipaddr,port) with the IP address and port number of the counterpart. s must be connected, either because you called s.connect or because s was generated by another socket object's accept method.
getsockname	s.getpeername( ) Returns a pair (ipaddr,port) with the IP address and port number of this socket on the local machine.
getsockopt	s.getsockopt(level,optname[,bufsize]) Returns the current value of an option on s. level can be any of four constants supplied for the purpose by module socket: SOL_SOCKET, for options related to the socket itself, or SOL_IP, SOL_TCP, or SOL_UDP, for options related to protocols IP, TCP, and UDP, respectively. optname can be any of many constants supplied by module socket to identify each socket option, with names starting with SO_. bufsize is normally absent, and then getsockopt returns the int value of the option. However, some options have values that are structures, not integers. In these cases, pass as bufsize the size of the appropriate structure, in bytesgetsockopt returns a binary string of bytes suitable for unpacking with module struct, covered in "The struct Module" on page 227. For example, here is how to find out if by default sockets are allowed to reuse addresses: import socket s = socket.socket( ) print s.getsockopt(s.SOL_SOCKET, s.SO_REUSEADDR) # emits 0, meaning that by default sockets do not reuse addresses
gettimeout	s.gettimeout( ) Returns a float, which is the timeout (in seconds, possibly with a fractional part) currently set on s, or None if s currently has no timeout behavior.
listen	s.listen(maxpending) Listens for connection attempts to the socket, allowing up to maxpending queued attempts at any time. maxpending must be greater than 0 and less than or equal to a system-dependent value, which on all contemporary systems is at least 5.
makefile	s.makefile(mode='r') Creates and returns a file object f (as covered in "File Objects" on page 216) that reads from and/or writes to the socket. You can close f and s independently; Python closes the underlying socket only when both f and s are closed.
recv	s.recv(bufsize) Receives up to bufsize bytes from the socket and returns a string with the data received. Returns an empty string when the socket is disconnected. If there is currently no data, blocks until the socket is disconnected or some data arrives.
recvfrom	s.recvfrom(bufsize) Receives up to bufsize bytes from the socket and returns a tuple (data,(ipaddr,port)). data is a string of the data received, and ipaddr and port are the IP address and port number of the sender. Useful with datagram sockets, which can receive data from many senders. If there is no data in the socket, blocks until data arrives.
send	s.send(string) Sends the bytes of string on the socket. Returns the number n of bytes sent. n may be lower than len(string); you must check for this, and resend substring string[n:] if needed. If there is no space in the socket's buffer, blocks until space appears.
sendall	s.sendall(string) Sends the bytes of string on the socket, blocking until all the bytes are sent.
sendto	s.sendto(string,(host,port)) Sends the bytes of string on the socket to destination host and port, and returns the number n of bytes sent. Useful with datagram sockets, which can send data to many destinations. You must not have called method s.bind. n may be lower than len(string); you must check for this, and resend string[n:] if it is nonempty.

20.1.3. Echo Server and Client Using TCP Sockets

Example 20-1 shows a TCP server that listens for connections on port 8881. When connected, the server loops, echoes all data back to the client, and goes back to accept another connection when the client is done. To terminate the server, hit the interrupt key with focus on the server's terminal window (console). The interrupt key, depending on your platform and settings, may be Ctrl-Break (typical on Windows) or Ctrl-C.

Example 20-1. TCP echo server

 import socket sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) sock.bind(('', 8881)) sock.listen(5) # loop waiting for connections # terminate with Ctrl-Break on Win32, Ctrl-C on Unix try:     while True:         newSocket, address = sock.accept( )         print "Connected from", address         while True:             receivedData = newSocket.recv(8192)             if not receivedData: break             newSocket.sendall(receivedData)         newSocket.close( )         print "Disconnected from", address finally:     sock.close( ) 

The argument passed to the newSocket.recv call, here 8192, is the maximum number of bytes to receive at a time. Receiving up to a few thousand bytes at a time is a good compromise between performance and memory consumption, and it's usual to specify a power of 2 (e.g., 8192==2**13) since memory allocation tends to round up to such powers anyway. It's important to close sock (to ensure we free its well-known port 8881 as soon as possible), so we use a try/finally statement to ensure we call sock.close. Closing newSocket, system-allocated on any suitable free port, is not as crucial, so we do not use a TRy/finally for it, although it would be fine to do so.

Example 20-2 shows a simple TCP client that connects to port 8881 on the local host, sends lines of data, and prints what it receives back from the server.

Example 20-2. TCP echo client

 import socket sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) sock.connect(('localhost', 8881)) print "Connected to server" data = """A few lines of data to test the operation of both server and client.""" for line in data.splitlines( ):     sock.sendall(line)     print "Sent:", line     response = sock.recv(8192)     print "Received:", response sock.close( ) 

Run the Example 20-1 server in a terminal window and try a few runs of Example 20-2.

20.1.4. Echo Server and Client Using UDP Sockets

Examples 20-3 and 20-4 implement an echo server and client with UDP (i.e., using datagram rather than stream sockets).

Example 20-3. UDP echo server

 import socket sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) sock.bind(('', 8881)) # loop waiting for datagrams (terminate with Ctrl-Break on Win32, Ctrl-C on Unix) try:     while True:         data, address = sock.recvfrom(8192)         print "Datagram from", address         sock.sendto(data, address) finally:     sock.close( ) 

Example 20-4. UDP echo client

 import socket sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) data = """A few lines of data to test the operation of both server and client.""" for line in data.splitlines( ):     sock.sendto(line, ('localhost', 8881))     print "Sent:", line     response = sock.recv(8192)     print "Received:", response sock.close( ) 

Run the server of Example 20-3 on a terminal window and try a few runs of Example 20-4. Examples 20-3 and 20-4, as well as Examples 20-1 and 20-2, can run independently at the same time. There is no interference or interaction, even though all are using port number 8881 on the local host, because TCP and UDP ports are separate. If you run Example 20-4 when the server of Example 20-3 is not running, you don't receive an error message: the client of Example 20-4 hangs forever, waiting for a response that will never arrive. Datagrams are not as robust and reliable as connections.

20.1.5. Socket Timeout Behavior

Standard C-level sockets, on most platforms, have no concept of timing out. By default, each socket operation blocks until it either succeeds or fails. There are advanced ways to ask for nonblocking sockets and to ensure that you perform socket operations only when they can't block (such as relying on module select, covered in "The select Module" on page 533). However, explicitly arranging for such behavior, particularly in a cross-platform way, can sometimes be complicated and difficult.

It's often simpler to deal with socket objects enriched by a timeout behavior. Each operation on such an object fails, with an exception indicating a timeout condition, if the operation has neither succeeded nor failed after the timeout period has elapsed. Such objects are internally implemented by using nonblocking sockets and selects, but your program is shielded from the complexities and deals only with objects that present a simple and intuitive interface. Functions getdefaulttimeout and setdefaulttimeout in the socket module, and methods gettimeout and settimeout on socket objects, let you set sockets' timeout behavior: the timeout value of each socket can be a floating-point number of seconds (thus you can also use a fraction of a second) or None to have a "normal" socket that doesn't time out.

With "normal" sockets (ones whose timeout value t is None), many methods, such as connect, accept, recv, and send, may block and wait "forever." When you call such methods on a socket s whose timeout value t is not None, if t seconds elapse since the call and the wait is still going on, then s stops waiting and raises socket.error.