Network programming

What it is and why it exists

Network programming is the work of designing programs in which two or more processes exchange data over network protocols. Applications do not usually manipulate Ethernet frames or TCP segments directly. They call the operating system’s network stack through a socket , which associates a read/write interface with an address family, transport protocol, local address, and peer address.

You meet it in HTTP services, database clients, message brokers, game sessions, device telemetry, and service-to-service RPC. Higher-level libraries hide many system calls, but they do not remove transport constraints. When a request is occasionally truncated, shutdown hangs, or memory keeps growing under load, those constraints often explain why.

A network program chooses communication semantics before it chooses an API. TCP and UDP both use ports to direct arriving data to a process, but they give applications different contracts. Code that confuses them may pass small loopback tests and then fail under packet loss, congestion, or long-lived connections.

TCP is a byte stream

TCP provides a reliable, ordered, bidirectional byte stream between two endpoints. “Reliable” means the protocol detects loss, retransmits, and delivers bytes to the receiving application in order. It does not mean a connection cannot fail or that a write necessarily arrives in full. Timeouts, resets, host restarts, and network partitions still leave applications with uncertain outcomes.

A byte stream has no message boundaries. If a sender writes b"red" and then b"blue", the receiver may read b"redblue", or it may get more fragments. The application protocol must define where each message ends.

UDP is datagrams

UDP sends datagrams . One successful send creates one datagram, and the receive API preserves that boundary. If the receive buffer is too small, excess content is truncated rather than saved for the next read.

UDP does not promise delivery, ordering, or duplicate suppression. An application that needs those properties must implement them at the application layer or choose a protocol that already does. Because UDP has no connection handshake, calling connect() on a UDP socket normally records a default peer and filters received sources; it does not establish a TCP-style connection.

A socket is a resource with a lifetime

A server’s listening socket queues connection requests. accept() returns a new connected socket for one client, while the listening socket remains available for other connections. A client normally resolves a host name and then calls connect() for one candidate address.

Sockets consume kernel resources and may retain ports, buffers, and protocol state. Ownership should be as explicit as it is for a file: who creates and closes the socket, who can cancel a blocking operation, and whether process shutdown stops new work before interrupting established connections. A context manager closes a descriptor, but a complete service still needs a shutdown order.

How it works

Name resolution produces candidate endpoints

An application often starts with a host and service name such as api.example and 443. The resolver turns them into one or more candidate socket addresses. Results may contain both IPv6 and IPv4 and may change across locations and time. Address, port, address family, and transport protocol together determine how a socket is created and connected.

Do not treat DNS as a dictionary that returns one permanent IP address. getaddrinfo() returns candidates, which a client tries sequentially or with bounded connection concurrency. Taking only the first result, forcing AF_INET, or caching the answer forever discards usable fallback paths.

A TCP connection pairs two one-way streams

A server calls socket(), bind(), listen(), and accept() in that order. A client creates a socket and calls connect(). After connection establishment, each endpoint can send and receive. Either direction may finish first, so “connection closed” is not always an instantaneous two-sided event.

send() copies as many bytes as it can into the local sending path and may return less than the input length. recv(n) returns up to n bytes currently available, not “whatever the peer sent last time.” In blocking mode, either call may wait. In nonblocking mode, a call reports that it should be retried later when it cannot make progress.

A TCP acknowledgment says that the peer’s protocol stack received the relevant bytes. It does not say that the peer committed a business transaction. If a client loses the connection before the response arrives, TCP state alone cannot tell whether the server finished the operation. Retrying a write requires application-level idempotency semantics or an idempotency key.

Framing recovers application messages

Message framing defines how complete messages are recognized in a byte stream. Common schemes use a fixed length, a delimiter, a length prefix, or a frame format defined by a higher-level protocol. The choice depends on whether payloads can contain a delimiter, whether a maximum size is known, and whether data can be parsed incrementally.

A length-prefixed protocol normally sends a fixed-width integer followed by that many payload bytes. A multi-byte integer needs an agreed byte order. Network protocols commonly use network byte order , which is big-endian. The ! prefix in a Python struct format selects network byte order explicitly.

A parser must not allocate an arbitrary buffer as soon as it sees a length. It validates the limit first and then waits for the complete frame. Its buffer may hold half a header, one complete frame plus part of the next, or several frames at once. All are normal input shapes.

Blocking, timeouts, and readiness

Blocking socket code is easy to follow, but every wait needs a way to end. A connection timeout, a per-read timeout, and a deadline for the whole operation are different. A peer can send a few bytes often enough to refresh individual read timeouts without ever finishing a message. External operations normally need a monotonic deadline spanning the whole operation.

Nonblocking I/O turns “cannot continue now” into normal control flow. selectors, poll, epoll, or an event loop may report that a socket is probably readable or writable, but readiness is not a completion promise. A handler still reads or writes until it cannot make more progress and retains the unfinished state.

Threads, async tasks, and event loops are waiting strategies. They do not supply framing, size limits, or cancellation propagation automatically. The number of connections a concurrency model can support also cannot be inferred from its API name; it must be measured with the intended workload.

Examples

A local TCP round trip

The first example binds an ephemeral port on the loopback address. The server handles one newline-terminated request and returns its uppercase form. makefile() wraps the socket in a buffered stream, and the newline is this tiny protocol’s message boundary.

Port 0 lets the operating system choose an unused port, so the example does not depend on a fixed one. It prints only the protocol result, not the port that changes on every run. The thread finishes before the listening socket closes, and the two with blocks make resource ownership visible.

Here, readline() waits for a newline, EOF, or an error. If the peer never sends a newline and keeps the connection open, the server waits forever; a production protocol also needs a message limit and a deadline. A simple delimiter does not remove the need for resource bounds.

Observe UDP datagram boundaries

The second example sends two datagrams to one loopback endpoint and receives them separately. The two output lines record this real run, but they do not prove that public-network UDP always arrives in sending order.

from socket import AF_INET, SOCK_DGRAM, socket


with socket(AF_INET, SOCK_DGRAM) as receiver:
    receiver.bind(("127.0.0.1", 0))
    receiver.settimeout(1.0)
    destination = receiver.getsockname()

    with socket(AF_INET, SOCK_DGRAM) as sender:
        sender.sendto(b"alpha", destination)
        sender.sendto(b"beta", destination)

    first, _ = receiver.recvfrom(1024)
    second, _ = receiver.recvfrom(1024)

print(f"datagram 1={first.decode()}")
print(f"datagram 2={second.decode()}")

datagram 1=alpha
datagram 2=beta

Each recvfrom() returns one datagram and its source address. The receive buffer is 1024 bytes, so a real protocol must guarantee that datagrams fit or use an API that reports truncation. A large datagram cannot be recovered with two calls to recvfrom().

Parse a length prefix incrementally

This parser uses a four-byte unsigned length prefix. It deliberately joins two messages and cuts the bytes at awkward positions to simulate possible TCP reads. The parser emits a message only when both its header and payload are complete.

from struct import Struct


HEADER = Struct("!I")
MAX_MESSAGE = 1024


def encode(message):
    return HEADER.pack(len(message)) + message


def extract_messages(buffer):
    messages = []
    while len(buffer) >= HEADER.size:
        (size,) = HEADER.unpack_from(buffer)
        if size > MAX_MESSAGE:
            raise ValueError("message too large")
        frame_size = HEADER.size + size
        if len(buffer) < frame_size:
            break
        messages.append(bytes(buffer[HEADER.size:frame_size]))
        del buffer[:frame_size]
    return messages


wire = encode(b"alpha") + encode(b"beta")
chunks = [wire[:3], wire[3:8], wire[8:]]
buffer = bytearray()

for chunk in chunks:
    buffer.extend(chunk)
    for message in extract_messages(buffer):
        print(f"message={message.decode()}")

print(f"remaining={len(buffer)}")

message=alpha
message=beta
remaining=0

The first chunk is not even a complete four-byte header, so the parser retains it. Later chunks complete the first frame and carry the second one, which means one pass may emit multiple messages. MAX_MESSAGE rejects an unreasonable length before reading its payload and prevents allocation based on an untrusted field.

This example copies messages and deletes bytes from the front of a bytearray. That is fine for explaining the protocol, not a claim about a high-throughput implementation. A production parser can use a read offset or ring buffer to reduce copying, but only after measurements show parsing cost matters.

Distinguish timeout, data, and EOF

The last example uses socketpair() to isolate state transitions without an external network. The first read times out because no data is available. After the sender writes and shuts down its write side, the receiver gets the data and then observes orderly EOF as an empty byte string.

from socket import SHUT_WR, socketpair


writer, reader = socketpair()
with writer, reader:
    reader.settimeout(0.02)
    try:
        reader.recv(4)
    except TimeoutError:
        print("read timed out")

    writer.sendall(b"done")
    writer.shutdown(SHUT_WR)

    print(f"data={reader.recv(4)!r}")
    print(f"eof={reader.recv(4)!r}")

read timed out
data=b'done'
eof=b''

A timeout says no data arrived before the deadline; it does not prove that the connection is dead. b'' denotes an orderly close of the peer’s sending direction and appears after previously buffered bytes are consumed. A reset normally raises an exception and must not be collapsed into either result as an empty response.

Pitfalls

Further reading

• Python 3.14 socket documentation
• Python 3.14 struct documentation
• RFC 9293: Transmission Control Protocol (TCP)
• RFC 768: User Datagram Protocol (UDP)
• RFC 8305: Happy Eyeballs Version 2