socketserver — Фреймворк для сетевых серверов

Примечания по созданию сервера

В диаграмме наследования пять классов, четыре из которых представляют синхронные серверы четырёх типов:

+------------+
| BaseServer |
+------------+
      |
      v
+-----------+        +------------------+
| TCPServer |------->| UnixStreamServer |
+-----------+        +------------------+
      |
      v
+-----------+        +--------------------+
| UDPServer |------->| UnixDatagramServer |
+-----------+        +--------------------+

Обратите внимание, что UnixDatagramServer наследуется от UDPServer, а не от UnixStreamServer — единственное различие между IP- и Unix-сервером — семейство адресов.

class socketserver.ForkingMixIn

class socketserver.ThreadingMixIn

Версии серверов с вилками и потоками можно создать, используя эти классы-микшины. Например, ThreadingUDPServer создаётся следующим образом:

class ThreadingUDPServer(ThreadingMixIn, UDPServer):
    pass

Класс-микшина ставится первым, так как он переопределяет метод, определённый в UDPServer. Установка различных атрибутов также изменяет поведение базового механизма сервера.

ForkingMixIn и упомянутые ниже классы с вилками доступны только на платформах POSIX, поддерживающих fork().

block_on_close

ForkingMixIn.server_close ожидает завершения всех дочерних процессов, если не установлен атрибут block_on_close.

ThreadingMixIn.server_close ожидает завершения всех нитей, кроме демонических, если не установлен атрибут block_on_close.

daemon_threads

Для ThreadingMixIn используйте демонические потоки, установив атрибут ThreadingMixIn.daemon_threads в True, чтобы не ждать завершения потоков.

Изменено в версии 3.7: ForkingMixIn.server_close и ThreadingMixIn.server_close теперь ожидают завершения всех дочерних процессов и потоков, не являющихся демоническими. Добавлен новый атрибут класса ForkingMixIn.block_on_close для выбора поведения до версии 3.7.

class socketserver.ForkingTCPServer

class socketserver.ForkingUDPServer

class socketserver.ThreadingTCPServer

class socketserver.ThreadingUDPServer

Эти классы предварительно определены с использованием классов-микшин.

Для реализации сервиса необходимо унаследовать класс от BaseRequestHandler и переопределить его метод handle(). Затем можно запустить различные версии сервиса, комбинируя один из классов сервера с классом обработчика запросов. Класс обработчика запросов должен отличаться для сервисов дейтаграмм или потоков. Это можно скрыть, используя подклассы обработчиков StreamRequestHandler или DatagramRequestHandler.

Конечно, вам всё равно нужно использовать голову! Например, нет смысла использовать сервер с вилками, если служба содержит состояние в памяти, которое может быть изменено различными запросами, так как изменения в дочернем процессе никогда не достигнут начального состояния, сохраняемого в родительском процессе и передаваемого каждому дочернему.

В этом случае можно использовать сервер с потоками, но, вероятно, вам придётся использовать блокировки для защиты целостности общих данных.

С другой стороны, если вы создаёте HTTP-сервер, где все данные хранятся во внешних источниках (например, в файловой системе), синхронный класс фактически сделает службу «глухой», пока обрабатывается один запрос — что может длиться очень долго, если клиент медленно получает все запрошенные данные. В этом случае подходит сервер с потоками или вилками.

В некоторых случаях может быть целесообразно обработать часть запроса синхронно, а завершить обработку в виртуальном дочернем процессе в зависимости от данных запроса. Это можно реализовать, используя синхронный сервер и выполняя явную вилку в методе обработчика запросов handle().

Другой подход к обработке нескольких одновременных запросов в среде, которая не поддерживает ни потоки, ни fork() (или где они слишком дороги или неподходящи для службы), заключается в сохранении явного таблицы частично завершённых запросов и использовании selectors для определения того, над каким запросом работать следующим (или следует ли обработать новый входящий запрос).

Это особенно важно для сервисов с потоками, где каждый клиент потенциально может быть подключён надолго (если потоки или подпроцессы нельзя использовать). См. asyncore для другого способа управления этим.

Объекты сервера

class socketserver.BaseServer(server_address, RequestHandlerClass)

Это суперкласс всех объектов сервера в модуле. Он определяет интерфейс, приведённый ниже, но не реализует большинство методов, что делается в подклассах. Два параметра хранятся в соответствующих атрибутах server_address и RequestHandlerClass.

fileno()

Возвращает целочисленный дескриптор файла для сокета, на котором сервер прослушивает соединения. Эта функция чаще всего передаётся в selectors, чтобы позволить отслеживать несколько серверов в одном процессе.

handle_request()

Обрабатывает одно запросы. Эта функция вызывает следующие методы в указанном порядке: get_request(), verify_request() и process_request(). Если пользовательский метод handle() класса обработчика вызывает исключение, вызывается метод handle_error() сервера. Если запрос не получен в течение timeout секунд, вызывается handle_timeout(), и handle_request() возвращает значение.

serve_forever(poll_interval=0.5)

Обрабатывает запросы до явного запроса shutdown(). Проверяет запрос на завершение каждые poll_interval секунд. Игнорирует атрибут timeout. Также вызывает service_actions(), который может использоваться подклассом или миксином для выполнения действий, специфичных для данного сервиса. Например, класс ForkingMixIn использует service_actions() для очистки процессов-зомби.

Изменено в версии 3.3: Добавлен вызов service_actions к методу serve_forever.

service_actions()

Вызывается в цикле serve_forever(). Этот метод может быть переопределён подклассами или миксинами для выполнения действий, специфичных для данного сервиса, таких как действия по очистке.

Введено в версии 3.3.

shutdown()

Указывает циклу serve_forever() на остановку и ожидает его завершения. shutdown() должен быть вызван во время выполнения serve_forever() в другом потоке, иначе произойдёт тупиковая ситуация.

server_close()

Очистка сервера. Может быть переопределён.

address_family

Семейство протоколов, к которому принадлежит сокет сервера. Примерами являются socket.AF_INET и socket.AF_UNIX.

RequestHandlerClass

Пользовательский класс обработчика запросов; для каждого запроса создаётся экземпляр этого класса.

server_address

Адрес, на котором прослушивает сервер. Формат адресов зависит от семейства протоколов; см. документацию модуля socket для получения подробных сведений. Для интернет-протоколов это кортеж, содержащий строку, представляющую адрес, и целое число — номер порта: ('127.0.0.1', 80), например.

socket

Объект сокета, на котором сервер будет прослушивать входящие запросы.

Классы серверов поддерживают следующие переменные класса:

allow_reuse_address

Разрешает ли сервер повторное использование адреса. По умолчанию это False, и это может быть изменено в подклассах.

request_queue_size

Размер очереди запросов. Если обработка одного запроса занимает много времени, все запросы, поступающие, пока сервер занят, помещаются в очередь до request_queue_size запросов. После заполнения очереди новые запросы от клиентов получат ошибку «Отказано в подключении». Значение по умолчанию обычно 5, но это может быть переопределено в подклассах.

socket_type

Тип сокета, используемого сервером; socket.SOCK_STREAM и socket.SOCK_DGRAM — два распространённых значения.

timeout

Время ожидания в секундах или None, если таймаут не требуется. Если handle_request() не получает входящих запросов в течение установленного времени ожидания, вызывается метод handle_timeout().

Существуют различные методы сервера, которые могут быть переопределены подклассами базовых классов сервера, таких как TCPServer; эти методы не нужны внешним пользователям объекта сервера.

finish_request(request, client_address)

Фактически обрабатывает запрос, создавая экземпляр RequestHandlerClass и вызывая его метод handle().

get_request()

Должен принять запрос от сокета и вернуть кортеж из 2-х элементов, содержащий новый объект сокета для связи с клиентом и адрес клиента.

handle_error(request, client_address)

Эта функция вызывается, если метод handle() экземпляра RequestHandlerClass вызывает исключение. По умолчанию выводится отладочная информация об исключении в стандартный вывод и продолжается обработка последующих запросов.

Изменено в версии 3.6: Теперь вызывается только для исключений, производных от класса Exception.

handle_timeout()

Эта функция вызывается, когда атрибут timeout установлен на значение, отличное от None, и истек срок ожидания без получения запросов. По умолчанию для серверов с форкингом выполняется сбор состояния завершенных дочерних процессов, в то время как в серверах с потоками эта функция ничего не делает.

process_request(request, client_address)

Вызывает finish_request() для создания экземпляра RequestHandlerClass. При необходимости эта функция может создать новый процесс или поток для обработки запроса; классы ForkingMixIn и ThreadingMixIn делают это.

server_activate()

Вызывается конструктором сервера для активации сервера. По умолчанию для TCP-сервера просто вызывается listen() на сокете сервера. Может быть переопределён.

server_bind()

Вызывается конструктором сервера для привязки сокета к нужному адресу. Может быть переопределён.

verify_request(request, client_address)

Должен возвращать булево значение; если значение равно True, запрос будет обработан, а если False, запрос будет отклонен. Эту функцию можно переопределить для реализации контроля доступа к серверу. По умолчанию функция всегда возвращает True.

Изменено в версии 3.6: Добавлена поддержка протокола менеджера контекста. Выход из менеджера контекста эквивалентен вызову server_close().

Обработчики запросов

class socketserver.BaseRequestHandler

Это суперкласс всех объектов обработчиков запросов. Он определяет интерфейс, представленный ниже. Конкретный подкласс обработчика запросов должен определить новый метод handle() и может переопределить любые другие методы. Новый экземпляр подкласса создаётся для каждого запроса.

setup()

Вызывается перед методом handle() для выполнения необходимых инициализирующих действий. По умолчанию ничего не делает.

handle()

Эта функция должна выполнить всю работу по обработке запроса. По умолчанию ничего не делает. Ей доступны несколько атрибутов экземпляра; запрос доступен как request; адрес клиента как client_address; и экземпляр сервера как server, в случае необходимости доступа к информации по серверу.

Тип request отличается для дейтаграммного и потокового сервисов. Для потоковых сервисов request — это объект сокета; для дейтаграммных сервисов request — это пара строки и сокета.

finish()

Вызывается после метода handle() для выполнения необходимых действий по очистке. По умолчанию ничего не делает. Если метод setup() вызывает исключение, эта функция не будет вызвана.

request

Новый объект socket.socket для связи с клиентом.

client_address

Адрес клиента, возвращаемый BaseServer.get_request().

server

Объект BaseServer, используемый для обработки запроса.

class socketserver.StreamRequestHandler

class socketserver.DatagramRequestHandler

Эти подклассы BaseRequestHandler переопределяют методы setup() и finish() и предоставляют атрибуты rfile и wfile.

rfile

Объект файла, из которого считывается запрос. Поддерживает читаемый интерфейс io.BufferedIOBase.

wfile

Объект файла, в который записывается ответ. Поддерживает записываемый интерфейс io.BufferedIOBase.

Изменено в версии 3.6: wfile также поддерживает записываемый интерфейс io.BufferedIOBase.

Примеры

import socketserver

class MyTCPHandler(socketserver.BaseRequestHandler):
    """
    The request handler class for our server.

    It is instantiated once per connection to the server, and must
    override the handle() method to implement communication to the
    client.
    """

    def handle(self):
        # self.request is the TCP socket connected to the client
        self.data = self.request.recv(1024).strip()
        print("{} wrote:".format(self.client_address[0]))
        print(self.data)
        # just send back the same data, but upper-cased
        self.request.sendall(self.data.upper())

if __name__ == "__main__":
    HOST, PORT = "localhost", 9999

    # Create the server, binding to localhost on port 9999
    with socketserver.TCPServer((HOST, PORT), MyTCPHandler) as server:
        # Activate the server; this will keep running until you
        # interrupt the program with Ctrl-C
        server.serve_forever()

class MyTCPHandler(socketserver.StreamRequestHandler):

    def handle(self):
        # self.rfile is a file-like object created by the handler;
        # we can now use e.g. readline() instead of raw recv() calls
        self.data = self.rfile.readline().strip()
        print("{} wrote:".format(self.client_address[0]))
        print(self.data)
        # Likewise, self.wfile is a file-like object used to write back
        # to the client
        self.wfile.write(self.data.upper())

import socket
import sys

HOST, PORT = "localhost", 9999
data = " ".join(sys.argv[1:])

# Create a socket (SOCK_STREAM means a TCP socket)
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
    # Connect to server and send data
    sock.connect((HOST, PORT))
    sock.sendall(bytes(data + "\n", "utf-8"))

    # Receive data from the server and shut down
    received = str(sock.recv(1024), "utf-8")

print("Sent:     {}".format(data))
print("Received: {}".format(received))

$ python TCPServer.py
127.0.0.1 wrote:
b'hello world with TCP'
127.0.0.1 wrote:
b'python is nice'

$ python TCPClient.py hello world with TCP
Sent:     hello world with TCP
Received: HELLO WORLD WITH TCP
$ python TCPClient.py python is nice
Sent:     python is nice
Received: PYTHON IS NICE

import socketserver

class MyUDPHandler(socketserver.BaseRequestHandler):
    """
    This class works similar to the TCP handler class, except that
    self.request consists of a pair of data and client socket, and since
    there is no connection the client address must be given explicitly
    when sending data back via sendto().
    """

    def handle(self):
        data = self.request[0].strip()
        socket = self.request[1]
        print("{} wrote:".format(self.client_address[0]))
        print(data)
        socket.sendto(data.upper(), self.client_address)

if __name__ == "__main__":
    HOST, PORT = "localhost", 9999
    with socketserver.UDPServer((HOST, PORT), MyUDPHandler) as server:
        server.serve_forever()

import socket
import sys

HOST, PORT = "localhost", 9999
data = " ".join(sys.argv[1:])

# SOCK_DGRAM is the socket type to use for UDP sockets
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

# As you can see, there is no connect() call; UDP has no connections.
# Instead, data is directly sent to the recipient via sendto().
sock.sendto(bytes(data + "\n", "utf-8"), (HOST, PORT))
received = str(sock.recv(1024), "utf-8")

print("Sent:     {}".format(data))
print("Received: {}".format(received))

import socket
import threading
import socketserver

class ThreadedTCPRequestHandler(socketserver.BaseRequestHandler):

    def handle(self):
        data = str(self.request.recv(1024), 'ascii')
        cur_thread = threading.current_thread()
        response = bytes("{}: {}".format(cur_thread.name, data), 'ascii')
        self.request.sendall(response)

class ThreadedTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
    pass

def client(ip, port, message):
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
        sock.connect((ip, port))
        sock.sendall(bytes(message, 'ascii'))
        response = str(sock.recv(1024), 'ascii')
        print("Received: {}".format(response))

if __name__ == "__main__":
    # Port 0 means to select an arbitrary unused port
    HOST, PORT = "localhost", 0

    server = ThreadedTCPServer((HOST, PORT), ThreadedTCPRequestHandler)
    with server:
        ip, port = server.server_address

        # Start a thread with the server -- that thread will then start one
        # more thread for each request
        server_thread = threading.Thread(target=server.serve_forever)
        # Exit the server thread when the main thread terminates
        server_thread.daemon = True
        server_thread.start()
        print("Server loop running in thread:", server_thread.name)

        client(ip, port, "Hello World 1")
        client(ip, port, "Hello World 2")
        client(ip, port, "Hello World 3")

        server.shutdown()

$ python ThreadedTCPServer.py
Server loop running in thread: Thread-1
Received: Thread-2: Hello World 1
Received: Thread-3: Hello World 2
Received: Thread-4: Hello World 3