==========================
TCP/IP Client and Server
==========================
Sockets can be configured to act as a *server* and listen for incoming
messages, or connect to other applications as a *client*. After both
ends of a TCP/IP socket are connected, communication is
bi-directional.
Echo Server
===========
This sample program, based on the one in the standard library
documentation, receives incoming messages and echos them back to the
sender. It starts by creating a TCP/IP socket.
.. literalinclude:: socket_echo_server.py
:lines: 10-14
Then :func:`bind` is used to associate the socket with the server
address. In this case, the address is ``localhost``, referring to the
current server, and the port number is 10000.
.. literalinclude:: socket_echo_server.py
:lines: 16-19
Calling :func:`listen` puts the socket into server mode, and
:func:`accept` waits for an incoming connection.
.. literalinclude:: socket_echo_server.py
:lines: 21-27
:func:`accept` returns an open connection between the server and
client, along with the address of the client. The connection is
actually a different socket on another port (assigned by the kernel).
Data is read from the connection with :func:`recv` and transmitted
with :func:`sendall`.
.. literalinclude:: socket_echo_server.py
:lines: 28-
When communication with a client is finished, the connection needs to
be cleaned up using :func:`close`. This example uses a
``try:finally`` block to ensure that :func:`close` is always called,
even in the event of an error.
Echo Client
===========
The client program sets up its :class:`socket` differently from the
way a server does. Instead of binding to a port and listening, it
uses :func:`connect` to attach the socket directly to the remote
address.
.. literalinclude:: socket_echo_client.py
:lines: 10-19
After the connection is established, data can be sent through the
:class:`socket` with :func:`sendall` and received with :func:`recv`,
just as in the server.
.. literalinclude:: socket_echo_client.py
:lines: 21-
When the entire message is sent and a copy received, the socket is
closed to free up the port.
Client and Server Together
==========================
The client and server should be run in separate terminal windows, so
they can communicate with each other. The server output is:
::
$ python ./socket_echo_server.py
starting up on localhost port 10000
waiting for a connection
connection from ('127.0.0.1', 52186)
received "This is the mess"
sending data back to the client
received "age. It will be"
sending data back to the client
received " repeated."
sending data back to the client
received ""
no more data from ('127.0.0.1', 52186)
waiting for a connection
The client output is:
::
$ python socket_echo_client.py
connecting to localhost port 10000
sending "This is the message. It will be repeated."
received "This is the mess"
received "age. It will be"
received " repeated."
closing socket
$
Easy Client Connections
=======================
TCP/IP clients can save a few steps by using the convenience function
:func:`create_connection` to connect to a server. The function takes
one argument, a two-value tuple containing the address of the server,
and derives the best address to use for the connection.
.. include:: socket_echo_client_easy.py
:literal:
:start-after: #end_pymotw_header
:func:`create_connection` uses :func:`getaddrinfo` to find candidate
connection parameters, and returns a :class:`socket` opened with the
first configuration that creates a successful connection. The
:attr:`family`, :attr:`type`, and :attr:`proto` attributes can be
examined to determine the type of :class:`socket` being returned.
::
$ python socket_echo_client_easy.py
Family : AF_INET
Type : SOCK_STREAM
Protocol: IPPROTO_TCP
sending "This is the message. It will be repeated."
received "This is the mess"
received "age. It will be"
received " repeated."
closing socket
Choosing an Address for Listening
=================================
It is important to bind a server to the correct address, so that
clients can communicate with it. The previous examples all used
``'localhost'`` as the IP address, which limits connections to clients
running on the same server. Use a public address of the server, such
as the value returned by :func:`gethostname`, to allow other hosts to
connect. This example modifies the echo server to listen on an
address specified via a command line argument.
.. include:: socket_echo_server_explicit.py
:literal:
:start-after: #end_pymotw_header
A similar modification to the client program is needed before the
server can be tested.
.. include:: socket_echo_client_explicit.py
:literal:
:start-after: #end_pymotw_header
After starting the server with the argument
``farnsworth.hellfly.net``, the :command:`netstat` command shows it
listening on the address for the named host.
::
$ host farnsworth.hellfly.net
farnsworth.hellfly.net has address 192.168.1.17
$ netstat -an
Active Internet connections (including servers)
Proto Recv-Q Send-Q Local Address Foreign Address (state)
...
tcp4 0 0 192.168.1.17.10000 *.* LISTEN
...
Running the the client on another host, passing
``farnsworth.hellfly.net`` as the host where the server is running,
produces:
::
$ hostname
homer
$ python socket_echo_client_explicit.py farnsworth.hellfly.net
connecting to farnsworth.hellfly.net port 10000
sending "This is the message. It will be repeated."
received "This is the mess"
received "age. It will be"
received " repeated."
And the server output is:
::
$ python ./socket_echo_server_explicit.py farnsworth.hellfly.net
starting up on farnsworth.hellfly.net port 10000
waiting for a connection
client connected: ('192.168.1.8', 57471)
received "This is the mess"
received "age. It will be"
received " repeated."
received ""
waiting for a connection
Many servers have more than one network interface, and therefore more
than one IP address. Rather than running separate copies of a service
bound to each IP address, use the special address :const:`INADDR_ANY`
to listen on all addresses at the same time. Although :mod:`socket`
defines a constant for :const:`INADDR_ANY`, it is an integer value and
must be converted to a dotted-notation string address before it can be
passed to :func:`bind`. As a shortcut, use the empty string ``''``
instead of doing the conversion.
.. include:: socket_echo_server_any.py
:literal:
:start-after: #end_pymotw_header
To see the actual address being used by a socket, call its
:func:`getsockname` method. After starting the service, running
:command:`netstat` again shows it listening for incoming connections
on any address.
::
$ netstat -an
Active Internet connections (including servers)
Proto Recv-Q Send-Q Local Address Foreign Address (state)
...
tcp4 0 0 *.10000 *.* LISTEN
...