Socket programming basics: TCP and UDP

One 7-byte word sent over a TCP socketOne end of a network connection as a program sees it: an object with methods such as send() and recv(). Python's socket module makes TCP sockets, which carry a stream of bytes, and UDP sockets, which carry datagrams. can reach recv(1024) as 7 bytes at once or as seven calls of 1 byte each: TCP delivers a stream of bytes, not messages. That fact, a time limit on every wait and a clean close are most of what makes socket code work outside a test.

Python’s socket module gives you both ends. socket.create_server() opens a server socket that listens on an address and a port, socket.create_connection() connects a client, and a with statement closes each of them. You will run a TCP echo server, read whole messages from a stream that splits them, and limit every wait. The browser runner cannot open sockets, so the network examples were recorded on 127.0.0.1, this computer’s own address.

A TCP server listens, a client connects, and both send bytes

A TCP server uses two kinds of socket: one that listens on a port, and a new one for every connection it accepts. Step through the first client of echo.py:

"""A TCP echo server and two clients on 127.0.0.1: listen, accept, send, receive and close."""
import socket
import threading

events = []                                      # the server's side, printed once the clients are done


def recv_exactly(sock, n):
    """Read exactly n bytes: recv() returns what has arrived, which may be less."""
    data = b""
    while len(data) < n:
        chunk = sock.recv(n - len(data))
        if not chunk:
            raise ConnectionError("the peer closed before the whole reply arrived")
        data += chunk
    return data


def serve(listener):
    for _ in range(2):                           # two clients, one after the other
        conn, (host, _port) = listener.accept()  # a new socket for this connection only
        with conn:
            events.append(f"accepted a connection from {host}")
            while data := conn.recv(1024):       # b"" means the client has closed its side
                events.append(f"received {data!r}")
                conn.sendall(data.upper())
            events.append("recv() returned b'': the client has gone")


with socket.create_server(("127.0.0.1", 0)) as listener:   # port 0: the system picks a free port
    port = listener.getsockname()[1]
    server = threading.Thread(target=serve, args=(listener,))
    server.start()
    for word in [b"namaste", b"vanakkam"]:
        with socket.create_connection(("127.0.0.1", port), timeout=5) as client:
            client.sendall(word)
            print(f"client sent {word!r}, got {recv_exactly(client, len(word))!r}")
    server.join()
print("server:", *events, sep="\n  ")

client sent b'namaste', got b'NAMASTE'
client sent b'vanakkam', got b'VANAKKAM'
server:
  accepted a connection from 127.0.0.1
  received b'namaste'
  recv() returned b'': the client has gone
  accepted a connection from 127.0.0.1
  received b'vanakkam'
  recv() returned b'': the client has gone

The server bound to 127.0.0.1, the loopback addressThe address 127.0.0.1 (::1 in IPv6) that always means this computer. A server bound to it accepts connections only from programs on the same machine., so only programs on this computer could connect, and port 0 let the system pick a free portA number from 1 to 65535 that, with the address, names one listening program on a computer, such as 443 for HTTPS.. accept() returned a new socket for each client, while the listening socket went on waiting. sendall() sends every byte or raises, unlike send(), which may send only part and returns how much. When recv() returns b"", the other side has closed its end, and the documentation states it plainly: a returned empty bytes object indicates that the client has disconnected.

recv() returns what has arrived, not a message

A message sent with one sendall() can arrive in several pieces, and two messages can arrive in one. RFC 9293 says that TCP segments often do not correspond one for one to the send calls of the application, so the receiver gets a stream of bytes with no mark where one send ended. Step through a read of the 5-byte message hello behind a 2-byte length, which arrives in three chunks. The list chunks stands for what three recv() calls would return:

chunks = [b"\x00", b"\x05he", b"llo"]      # what three recv() calls return: TCP split the message
received = b""
size = None                                  # the length prefix is not known yet
while size is None or len(received) < 2 + size:
    received += chunks.pop(0)                # recv() returns whatever has arrived
    if size is None and len(received) >= 2:
        size = int.from_bytes(received[:2])  # the prefix is complete: the message length is known
print("length prefix:", size)
print("message:", received[2:2 + size])

length prefix: 5
message: b'hello'

The loop could not know the length of the message until the second chunk had brought the whole prefix, and it went on reading until it held all 7 bytes. recv_exactly() in echo.py is the same loop as a function: it asks each time only for the bytes still missing, and treats b"" as the connection closing in the middle. Every protocol over TCP also needs framingframing: The rule a protocol uses to mark where each message ends in a stream of bytes, such as a newline after each message or a length before it. TCP keeps no record of where one write ended, so every protocol over it needs one. More in “Networking with asyncio streams”, a rule for where a message ends: a newline after each message, or a length prefixlength prefix: A fixed-size number written before each message that gives its size in bytes, often 4 bytes in big-endian order. The receiver reads the number, then exactly that many bytes, whatever they contain. More in “Networking with asyncio streams” before it, as here.

Every wait gets a time limit, and every socket gets closed

By default a socket waits for ever: a peer that accepts a connection and then sends nothing holds recv() until the program is stopped. settimeout(seconds) limits every blocking call on the socket, and the timeout argument of create_connection() sets the same limit from the start. Since Python 3.10, socket.timeout is an alias of TimeoutError. This run uses a connected pair of sockets inside one program, which needs no network:

"""Timeouts and closing, on a connected pair of sockets: a silent peer, a closed peer, and the with statement."""
import socket
import time

left, right = socket.socketpair()      # two connected sockets in this program, so no network is needed
with left, right:
    left.settimeout(0.2)               # every blocking call on left now waits at most 0.2 s
    start = time.monotonic()
    try:
        left.recv(1024)                # right never sends anything
    except TimeoutError as e:
        print(f"silent peer: {type(e).__name__} ({e}) after {time.monotonic() - start:.1f} s")
    right.close()                      # the peer closes its end
    print("closed peer: recv() returned", left.recv(1024))
print("after the with block, left is closed:", left.fileno() == -1)

silent peer: TimeoutError (timed out) after 0.2 s
closed peer: recv() returned b''
after the with block, left is closed: True

The with block closed both sockets on the way out, as it would after an exception, and a closed socket reports fileno() as −1. Five more tools come up as soon as programs talk for real:

• Framing choices: newline-ended messages are simple but break on a message that contains a newline; a length prefix carries any bytes but needs a size limit.
• Half-close: shutdown(SHUT_WR) says that you have sent everything, while the socket can still read the answer.
• Binding: 127.0.0.1 keeps a server to this machine, '' opens it on every interface, and one address and port take one server.
• UDP: a SOCK_DGRAM socket sends single datagramsOne self-contained message sent by UDP. It arrives whole or not at all, and datagrams may be lost, repeated or delivered in another order. that keep their boundaries but may be lost. UDP needs no connection and no accept(), so one socket can hear many senders, and the program must cope with loss itself.
• Higher levels: HTTP clients and asyncio streams do this work for you, and most programs should use them. HTTP fits any service that already speaks it, such as a web API, and asyncio streams fit a TCP protocol of your own that keeps many connections open.

Practise: read whole messages from a stream that splits them

Write recv_exactly() and recv_line(). The sample tests use a fake socket that returns from 1 to 5 bytes at a time, chosen by a seeded random generator, so your loops meet the same splits on every run. Once they pass, a practice session starts from your weakest concept, and each answer is explained as soon as you give it.

def recv_exactly(sock, n):
    """Exactly n bytes from sock; ConnectionError if it closes first."""
    return sock.recv(n)


def recv_line(sock, limit=1024):
    """The bytes up to and including the first newline; ValueError past limit, ConnectionError if it closes."""
    return sock.recv(limit)

import random

from netio import recv_exactly, recv_line


class ChunkySocket:
    """Returns from 1 to 5 bytes per recv(), chosen by a seeded random generator, then b"" when the data runs out."""

    def __init__(self, data, seed=7):
        self.data, self.rng, self.calls = data, random.Random(seed), 0

    def recv(self, n):
        self.calls += 1
        size = min(n, self.rng.randint(1, 5))
        part, self.data = self.data[:size], self.data[size:]
        return part


class OneThenAsked:
    """The first recv() returns one byte, every later one as many as it is asked for."""

    def __init__(self, data):
        self.data, self.first = data, True

    def recv(self, n):
        size = 1 if self.first else n
        self.first = False
        part, self.data = self.data[:size], self.data[size:]
        return part


def raises(error, call, *args):
    try:
        call(*args)
    except error:
        return True
    return False


def test_exactly_collects_small_chunks():
    """recv_exactly() keeps calling recv() until it has n bytes"""
    sock = ChunkySocket(b"0123456789abcdef")
    assert recv_exactly(sock, 10) == b"0123456789"
    assert recv_exactly(sock, 6) == b"abcdef"
    assert sock.calls > 2


def test_exactly_asks_only_for_the_missing_bytes():
    """recv_exactly() never takes a byte of the next message"""
    sock = OneThenAsked(b"abcdefgh")
    assert recv_exactly(sock, 4) == b"abcd"
    assert sock.data == b"efgh"


def test_exactly_zero_and_early_close():
    """zero bytes need no read, and a close before n bytes is an error"""
    assert recv_exactly(ChunkySocket(b"abc"), 0) == b""
    assert raises(ConnectionError, recv_exactly, ChunkySocket(b"abc"), 5)


def test_line_stops_at_the_newline():
    """recv_line() returns one line, and the next call returns the next"""
    sock = ChunkySocket(b"ROLL 21\nROLL 22\n")
    assert recv_line(sock) == b"ROLL 21\n"
    assert recv_line(sock) == b"ROLL 22\n"


def test_line_limit_and_close():
    """too long without a newline, or closed first, is an error"""
    assert raises(ValueError, recv_line, ChunkySocket(b"x" * 50), 20)
    assert raises(ConnectionError, recv_line, ChunkySocket(b"no newline"))

Framing messages, closing cleanly and binding with care Pro: opens with a Pro, Premium or Ultimate pass

UDP datagrams, and choosing the right level for a program Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

Key takeaways

• A TCP server listens with create_server(), accept() returns a new socket per client, and recv() returning b"" means the other side has closed.
• recv() returns what has arrived, so read in a loop until your framing, a newline or a length prefix, says the message is complete.
• Give every socket a timeout and a with block, so that a silent peer cannot hold a program and a socket is closed on every path.