0%

Open a Connection · practice

Connect, Send, Receive

Chapter 3 ended with addresses ready to connect to, pairs such as ("127.0.0.1", 8080). This lesson connects to one. A program does that through a socket: the a program uses to send and receive bytes over a connection. You open one, send bytes into it, read bytes out of it, and close it.

Open, send, receive, close

Here are all four steps against a server on your own machine. Read it now; you will write your own version below.

import socket

with socket.create_connection(("127.0.0.1", 9000), timeout=2.0) as sock:
    sock.sendall(b"hello")
    reply = sock.recv(1024)
print(reply)

socket.create_connection takes a socket address and opens a to it. If the host is a name, it resolves it first, the way Chapter 3’s getaddrinfo did. It returns a connected socket.

The with block closes the socket on the way out, as it closes a file: when the block ends normally, and also when an error leaves it early. Closing tells the other side you are done and gives the connection’s resources back to the system. A program that forgets to close may keep both until it exits.

The timeout=2.0 is the habit from Python in Practice: never wait without a bound. The next lesson shows exactly what it bounds.

Sockets carry bytes, not text. sendall takes a bytes and recv returns one, so text goes through the Chapter 2 conversions on the way: text.encode("utf-8") before sending, reply.decode("utf-8") after receiving.

There are two ways to send. sock.send(data) hands as many bytes as the system will take right now to the connection, which may be only part of data, and returns how many it took; sending the rest is your job. sock.sendall(data) keeps going until every byte has been handed over. This course always uses sendall.

sock.recv(1024) waits until some bytes have arrived and returns them, at most 1,024. It returns whatever is there, not “one message”. For the short messages in this chapter, one call returns the whole reply. That is a simplification, and Chapter 6 takes it apart.

A client sends its request with sock.sendall(data) instead of sock.send(data). Why?

In with connect(address, timeout=2.0) as sock:, when is the connection closed?

A function in a parameter

Open echo_client.py in the project. The you will write starts like this:

def ask(address, text, *, timeout=2.0, connect=socket.create_connection):
    """Send text to the server at address and return its reply as text."""

Look at the default of connect. It is socket.create_connection with no parentheses after it. Without parentheses nothing is called: the name refers to the function itself, and a function is a value like any other. You can store it under another name or pass it as an , and calling that name calls the function.

So inside ask, you open the connection with:

with connect(address, timeout=timeout) as sock:

connect holds whatever function the caller passed, and socket.create_connection when they passed nothing. Called this way it does exactly what socket.create_connection(address, timeout=timeout) would.

This is the same shape as the session=None in Python in Practice, where a test handed the API client a fake session. Here a test can hand ask a different connect function and see what ask does with it, without a network. Lesson 5 does exactly that.

transform holds a function. What does this print?

def shout(text):
    return text.upper()


def apply(text, *, transform=shout):
    return transform(text)


print(apply("hi"))
print(apply("hi", transform=len))

A helper plays the server

To try ask, something has to be listening at the other end. Normally that means a second program in a second , and each lesson here has one terminal. So this course supplies pl_net.py, a helper written for this course that plays the program on the other end.

python pl_net.py client echo starts a small echo server on 127.0.0.1, one that sends back whatever it receives. Then it calls your project’s main() with that server’s and the text hello, echo, and prints what each side sent. main is already written: it reads the arguments, calls ask, and prints the reply. It also takes a connect parameter and passes it on to ask, so the same door is open one level up.

Try it now, before writing anything:

python pl_net.py client echo

The first line names the scenario and the port number the server was given, which differs from run to run. The rest looks like this:

--- your program ---
--- transcript ---
server: your program never connected
--- result ---
your main() raised NotImplementedError
pl_net: every thread has stopped

--- your program --- holds whatever your code printed: nothing yet. --- transcript --- the bytes each side sent, as pl_net saw them. --- result --- says how your main() ended. Here ask is still the stub, so it raised NotImplementedError before connecting. The last line is pl_net confirming that nothing it started is still waiting.

Once ask works, the same command shows the round trip:

--- your program ---
hello, echo
--- transcript ---
client -> server  b'hello, echo'  (11 bytes)
server -> client  b'hello, echo'  (11 bytes)
server: the client closed the connection
--- result ---
your main() returned 0
pl_net: every thread has stopped

Eleven bytes went out, the same eleven came back, and your main printed them as text. The line server: the client closed the connection is your with block at work.

pl_net only shows you what happened. Nothing reads its output, and it is not part of Check my work.

You can also run python echo_client.py --port NUMBER TEXT yourself. With no server listening at that port, it can only fail; Lesson 4 does exactly that, on purpose.

Your task

Write the body of ask in echo_client.py:

  1. Open the connection with connect(address, timeout=timeout) in a with block.

  2. Send text encoded with , using sendall.

  3. Read the reply with one recv(1024).

  4. Return the reply decoded with UTF-8.

That is four lines inside the function. Run python pl_net.py client echo until you see the round trip above, then press Check my work. A server that never answers is the next lesson’s problem.

Task

Write the body of ask(address, text, *, timeout=2.0, connect=socket.create_connection) in echo_client.py. It should:

  1. call connect(address, timeout=timeout) once and use the it returns in a with block;

  2. send text encoded with , naming the encoding, for example text.encode("utf-8"), using sendall;

  3. read the reply with one recv(1024);

  4. return the reply decoded with UTF-8, as text.

Leave describe_failure and main as they are. In the , python pl_net.py client echo shows your client talking to a supplied echo server.

Then press Check my work. The check calls ask with a stand-in connect that records the address and timeout it receives and hands back a stand-in socket. It checks that ask connects once with its timeout, sends every byte of a text you have not seen, returns the reply as text, and closes the connection. It does not open a real connection or read the terminal.