`socketserver.md`

401 строк · 32.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.3/library/socketserver.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 21.21. [`socketserver`](https://python-all.ru/3.3/library/socketserver.html#module-socketserver) – Фреймворк для сетевых серверов89**Исходный код:** [Lib/socketserver.py](https://python-all.ru/src/3.3/Lib/socketserver.py)1011---1213Модуль [`socketserver`](https://python-all.ru/3.3/library/socketserver.html#module-socketserver) упрощает задачу написания сетевых серверов.1415Существует четыре базовых класса серверов: `TCPServer` использует протокол TCP, который обеспечивает непрерывные потоки данных между клиентом и сервером. `UDPServer` использует дейтаграммы – дискретные пакеты информации, которые могут прийти не по порядку или потеряться при передаче. Реже используемые классы `UnixStreamServer` и `UnixDatagramServer` похожи, но используют сокеты домена Unix; они недоступны на платформах, отличных от Unix. Дополнительные сведения о сетевом программировании можно найти в таких книгах, как UNIX Network Programming У. Ричарда Стивенса или Win32 Network Programming Ральфа Дэвиса.1617Эти четыре класса обрабатывают запросы *синхронно*; каждый запрос должен быть завершен до того, как может начаться следующий. Это не подходит, если каждый запрос требует много времени на выполнение из-за вычислительной сложности или из-за возврата большого объема данных, которые клиент обрабатывает медленно. Решение – создавать отдельный процесс или поток для обработки каждого запроса; миксин-классы `ForkingMixIn` и `ThreadingMixIn` можно использовать для поддержки асинхронного поведения.1819Создание сервера требует нескольких шагов. Сначала необходимо создать класс-обработчик запросов, унаследовав его от класса `BaseRequestHandler` и переопределив его метод `handle()`; этот метод будет обрабатывать входящие запросы. Затем нужно создать экземпляр одного из классов серверов, передав ему адрес сервера и класс-обработчик запросов. В конце вызовите метод `handle_request()` или `serve_forever()` объекта сервера для обработки одного или нескольких запросов.2021При наследовании от `ThreadingMixIn` для поведения с потоками следует явно указать, как должны вести себя потоки при внезапном завершении. Класс `ThreadingMixIn` определяет атрибут *daemon\_threads*, который указывает, должен ли сервер ждать завершения потоков. Флаг нужно установить явно, если требуется, чтобы потоки работали автономно; по умолчанию [`False`](https://python-all.ru/3.3/library/constants.html#False), то есть Python не завершится, пока не завершатся все потоки, созданные `ThreadingMixIn`.2223Классы серверов имеют одни и те же внешние методы и атрибуты, независимо от того, какой сетевой протокол они используют.2425## 21.21.1. Примечания по созданию сервера2627В иерархии наследования пять классов, четыре из которых представляют синхронные серверы четырёх типов:2829```python30+------------+31| BaseServer |32+------------+33      |34      v35+-----------+        +------------------+36| TCPServer |------->| UnixStreamServer |37+-----------+        +------------------+38      |39      v40+-----------+        +--------------------+41| UDPServer |------->| UnixDatagramServer |42+-----------+        +--------------------+43```4445Обратите внимание, что `UnixDatagramServer` наследует от `UDPServer`, а не от `UnixStreamServer` – единственное различие между IP- и Unix-стрим-сервером заключается в семействе адресов, которое просто повторяется в обоих Unix-классах серверов.4647Версии с порождением процессов и потоками для каждого типа сервера можно создать с помощью миксин-классов `ForkingMixIn` и `ThreadingMixIn`. Например, класс потокового UDP-сервера создаётся следующим образом:4849```python50class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass51```5253Миксин-класс должен стоять первым, поскольку он переопределяет метод, определённый в `UDPServer`. Установка различных атрибутов также изменяет поведение базового механизма сервера.5455Для реализации службы необходимо создать класс, унаследованный от `BaseRequestHandler`, и переопределить его метод `handle()`. Затем можно запускать различные версии службы, комбинируя один из классов сервера с классом-обработчиком запросов. Класс-обработчик запросов должен различаться для дейтаграммных и потоковых служб. Это можно скрыть, используя подклассы обработчиков `StreamRequestHandler` или `DatagramRequestHandler`.5657Конечно, нужно подходить с умом. Например, нет смысла использовать сервер с порождением процессов (forking), если служба хранит состояние в памяти, которое может изменяться разными запросами, потому что изменения в дочернем процессе никогда не попадут в исходное состояние, хранящееся в родительском процессе и передаваемое каждому дочернему. В этом случае можно использовать потоковый сервер (threading), но, скорее всего, придётся использовать блокировки для защиты целостности общих данных.5859С другой стороны, если создаётся HTTP-сервер, где все данные хранятся внешне (например, в файловой системе), синхронный класс фактически сделает службу «глухой» на время обработки одного запроса – что может занять очень много времени, если клиент медленно получает все запрошенные данные. Здесь подойдёт потоковый сервер или сервер с порождением процессов.6061В некоторых случаях может быть целесообразно обработать часть запроса синхронно, но завершить обработку в порождённом дочернем процессе в зависимости от данных запроса. Это можно реализовать, используя синхронный сервер и выполняя явный вызов fork в методе `handle()` класса-обработчика запросов.6263Другой подход к обработке нескольких одновременных запросов в среде, не поддерживающей ни потоки, ни [`fork()`](https://python-all.ru/3.3/library/os.html#os.fork) (или где они слишком дороги или неподходящи для службы), заключается в ведении явной таблицы частично завершённых запросов и использовании [`select()`](https://python-all.ru/3.3/library/select.html#select.select) для принятия решения, над каким запросом работать следующим (или обрабатывать ли новый входящий запрос). Это особенно важно для потоковых служб, где каждый клиент может быть подключён длительное время (если нельзя использовать потоки или подпроцессы). См. [`asyncore`](https://python-all.ru/3.3/library/asyncore.html#module-asyncore) для другого способа управления этим.6465## 21.21.2. Объекты сервера6667#### `class socketserver.BaseServer`6869Это суперкласс всех объектов серверов в модуле. Он определяет интерфейс, приведённый ниже, но не реализует большинство методов – это делается в подклассах.7071#### `BaseServer.fileno()`7273Возвращает целочисленный файловый дескриптор для сокета, на котором сервер прослушивает соединения. Эта функция чаще всего передаётся в [`select.select()`](https://python-all.ru/3.3/library/select.html#select.select), чтобы обеспечить мониторинг нескольких серверов в одном процессе.7475#### `BaseServer.handle_request()`7677Обрабатывает один запрос. Эта функция вызывает следующие методы по порядку: [`get_request()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.get_request), [`verify_request()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.verify_request) и [`process_request()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.process_request). Если предоставленный пользователем метод `handle()` класса-обработчика вызывает исключение, будет вызван метод [`handle_error()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.handle_error) сервера. Если в течение `self.timeout` секунд не получено ни одного запроса, будет вызван [`handle_timeout()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.handle_timeout), и [`handle_request()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.handle_request) вернёт управление.7879#### `BaseServer.serve_forever(poll_interval=0.5)`8081Обрабатывает запросы до тех пор, пока не поступит явный запрос на [`shutdown()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.shutdown). Проверяет необходимость завершения каждые *poll\_interval* секунд. Игнорирует `self.timeout`. Также вызывает [`service_actions()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.service_actions), который может использоваться подклассом или миксином для предоставления действий, специфичных для данной службы. Например, класс `ForkingMixIn` использует [`service_actions()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.service_actions) для очистки зомби-процессов дочерних процессов.8283Изменено в версии 3.3: В метод `serve_forever` добавлен вызов `service_actions`.8485#### `BaseServer.service_actions()`8687Вызывается в цикле [`serve_forever()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.serve_forever). Этот метод может быть переопределён подклассами или миксин-классами для выполнения действий, специфичных для данной службы, например, очистки.8889Новое в версии 3.3.9091#### `BaseServer.shutdown()`9293Даёт команду циклу [`serve_forever()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.serve_forever) остановиться и ожидает его завершения.9495#### `BaseServer.address_family`9697Семейство протоколов, к которому принадлежит сокет сервера. Типичные примеры: [`socket.AF_INET`](https://python-all.ru/3.3/library/socket.html#socket.AF_INET) и [`socket.AF_UNIX`](https://python-all.ru/3.3/library/socket.html#socket.AF_UNIX).9899#### `BaseServer.RequestHandlerClass`100101Класс обработчика запросов, предоставленный пользователем; экземпляр этого класса создаётся для каждого запроса.102103#### `BaseServer.server_address`104105Адрес, на котором сервер прослушивает соединения. Формат адресов зависит от семейства протоколов; подробнее см. документацию модуля socket. Для интернет-протоколов это кортеж, содержащий строку с адресом и целочисленный номер порта: `('127.0.0.1', 80)`, например.106107#### `BaseServer.socket`108109Объект сокета, через который сервер будет принимать входящие запросы.110111Классы серверов поддерживают следующие переменные класса:112113#### `BaseServer.allow_reuse_address`114115Определяет, разрешает ли сервер повторное использование адреса. По умолчанию [`False`](https://python-all.ru/3.3/library/constants.html#False), и может быть установлен в подклассах для изменения политики.116117#### `BaseServer.request_queue_size`118119Размер очереди запросов. Если обработка одного запроса занимает много времени, все запросы, поступающие во время занятости сервера, помещаются в очередь – до [`request_queue_size`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.request_queue_size) запросов. Когда очередь заполнена, последующие запросы от клиентов получают ошибку «Connection denied». Обычно значение по умолчанию равно 5, но его можно переопределить в подклассах.120121#### `BaseServer.socket_type`122123Тип сокета, используемого сервером; [`socket.SOCK_STREAM`](https://python-all.ru/3.3/library/socket.html#socket.SOCK_STREAM) и [`socket.SOCK_DGRAM`](https://python-all.ru/3.3/library/socket.html#socket.SOCK_DGRAM) – два распространённых значения.124125#### `BaseServer.timeout`126127Длительность тайм-аута в секундах или [`None`](https://python-all.ru/3.3/library/constants.html#None), если тайм-аут не нужен. Если [`handle_request()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.handle_request) не получает входящих запросов в течение тайм-аута, вызывается метод [`handle_timeout()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.handle_timeout).128129Существует несколько методов сервера, которые могут быть переопределены подклассами базовых классов сервера, например `TCPServer`; эти методы не предназначены для внешних пользователей объекта сервера.130131#### `BaseServer.finish_request()`132133Непосредственно обрабатывает запрос, создавая экземпляр [`RequestHandlerClass`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.RequestHandlerClass) и вызывая его метод `handle()`.134135#### `BaseServer.get_request()`136137Должен принять запрос из сокета и вернуть кортеж из двух элементов, содержащий *новый* объект сокета для взаимодействия с клиентом и адрес клиента.138139#### `BaseServer.handle_error(request, client_address)`140141Эта функция вызывается, если метод `handle()` класса [`RequestHandlerClass`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.RequestHandlerClass) вызывает исключение. По умолчанию трассировка выводится в стандартный вывод, и обработка последующих запросов продолжается.142143#### `BaseServer.handle_timeout()`144145Эта функция вызывается, когда атрибут [`timeout`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.timeout) установлен в значение, отличное от [`None`](https://python-all.ru/3.3/library/constants.html#None), и по истечении тайм-аута не было получено ни одного запроса. В серверах с порождением процессов (forking) по умолчанию собирается статус завершившихся дочерних процессов, а в серверах с потоками этот метод ничего не делает.146147#### `BaseServer.process_request(request, client_address)`148149Вызывает [`finish_request()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.finish_request) для создания экземпляра [`RequestHandlerClass`](https://python-all.ru/3.3/library/socketserver.html#socketserver.BaseServer.RequestHandlerClass). При необходимости эта функция может создать новый процесс или поток для обработки запроса; классы `ForkingMixIn` и `ThreadingMixIn` делают это.150151#### `BaseServer.server_activate()`152153Вызывается конструктором сервера для его активации. По умолчанию просто вызывает `listen()` на сокете сервера. Может быть переопределён.154155#### `BaseServer.server_bind()`156157Вызывается конструктором сервера для привязки сокета к нужному адресу. Можно переопределить.158159#### `BaseServer.verify_request(request, client_address)`160161Должен возвращать логическое значение; если [`True`](https://python-all.ru/3.3/library/constants.html#True), запрос будет обработан, а если [`False`](https://python-all.ru/3.3/library/constants.html#False), запрос будет отклонён. Эту функцию можно переопределить для реализации контроля доступа к серверу. Реализация по умолчанию всегда возвращает [`True`](https://python-all.ru/3.3/library/constants.html#True).162163## 21.21.3. Объекты RequestHandler164165Класс обработчика запросов должен определять новый метод `handle()` и может переопределять любые из следующих методов. Для каждого запроса создаётся новый экземпляр.166167#### `RequestHandler.finish()`168169Вызывается после метода [`handle()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.RequestHandler.handle) для выполнения необходимых действий по очистке. Реализация по умолчанию ничего не делает. Если [`setup()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.RequestHandler.setup) вызывает исключение, эта функция не будет вызвана.170171#### `RequestHandler.handle()`172173Эта функция должна выполнять всю работу по обслуживанию запроса. Реализация по умолчанию ничего не делает. Для неё доступны несколько атрибутов экземпляра: запрос доступен как `self.request`; адрес клиента как `self.client_address`; и экземпляр сервера как `self.server`, на случай, если потребуется доступ к информации, специфичной для сервера.174175Тип `self.request` различается для датаграммных и потоковых служб. Для потоковых служб `self.request` – это объект сокета; для датаграммных – `self.request` представляет собой пару из строки и сокета. Однако это можно скрыть, используя подклассы обработчика запросов `StreamRequestHandler` или `DatagramRequestHandler`, которые переопределяют методы [`setup()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.RequestHandler.setup) и [`finish()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.RequestHandler.finish) и предоставляют атрибуты `self.rfile` и `self.wfile`. `self.rfile` и `self.wfile` можно читать или записывать соответственно для получения данных запроса или возврата данных клиенту.176177#### `RequestHandler.setup()`178179Вызывается перед методом [`handle()`](https://python-all.ru/3.3/library/socketserver.html#socketserver.RequestHandler.handle) для выполнения необходимых действий по инициализации. Реализация по умолчанию ничего не делает.180181## 21.21.4. Примеры182183### 21.21.4.1. `socketserver.TCPServer` Пример184185Это серверная сторона:186187```python188import socketserver189190class MyTCPHandler(socketserver.BaseRequestHandler):191    """192    Класс RequestHandler для нашего сервера.193194    Он создаётся один раз на каждое подключение к серверу и должен195    переопределять метод handle() для реализации взаимодействия с196    клиентом.197    """198199    def handle(self):200        # self.request – это TCP-сокет, подключённый к клиенту201        self.data = self.request.recv(1024).strip()202        print("{} wrote:".format(self.client_address[0]))203        print(self.data)204        # просто отправляет обратно те же данные, но в верхнем регистре205        self.request.sendall(self.data.upper())206207if __name__ == "__main__":208    HOST, PORT = "localhost", 9999209210    # Создаём сервер, привязываясь к localhost на порту 9999211    server = socketserver.TCPServer((HOST, PORT), MyTCPHandler)212213    # Запускаем сервер; он будет работать, пока вы214    # не прервёте программу с помощью Ctrl-C215    server.serve_forever()216```217218Альтернативный класс обработчика запросов, который использует потоки (объекты, подобные файлам, упрощающие взаимодействие за счет предоставления стандартного файлового интерфейса):219220```python221class MyTCPHandler(socketserver.StreamRequestHandler):222223    def handle(self):224        # self.rfile – это файлоподобный объект, созданный обработчиком;225        # теперь можно использовать, например, readline() вместо прямых вызовов recv()226        self.data = self.rfile.readline().strip()227        print("{} wrote:".format(self.client_address[0]))228        print(self.data)229        # Аналогично, self.wfile – это файлоподобный объект, используемый для записи ответа230        # клиенту231        self.wfile.write(self.data.upper())232```233234Разница в том, что вызов `readline()` во втором обработчике вызывает `recv()` несколько раз, пока не встретит символ новой строки, тогда как одиночный вызов `recv()` в первом обработчике просто возвращает то, что было отправлено от клиента за один вызов `sendall()`.235236Это клиентская сторона:237238```python239import socket240import sys241242HOST, PORT = "localhost", 9999243data = " ".join(sys.argv[1:])244245# Создать сокет (SOCK_STREAM означает TCP-сокет)246sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)247248try:249    # Подключиться к серверу и отправить данные250    sock.connect((HOST, PORT))251    sock.sendall(bytes(data + "\n", "utf-8"))252253    # Получить данные от сервера и завершить работу254    received = str(sock.recv(1024), "utf-8")255finally:256    sock.close()257258print("Sent:     {}".format(data))259print("Received: {}".format(received))260```261262Результат работы примера должен выглядеть примерно так:263264Сервер:265266```python267$ python TCPServer.py268127.0.0.1 wrote:269b'hello world with TCP'270127.0.0.1 wrote:271b'python is nice'272```273274Клиент:275276```python277$ python TCPClient.py hello world with TCP278Sent:     hello world with TCP279Received: HELLO WORLD WITH TCP280$ python TCPClient.py python is nice281Sent:     python is nice282Received: PYTHON IS NICE283```284285### 21.21.4.2. `socketserver.UDPServer` Пример286287Это серверная сторона:288289```python290import socketserver291292class MyUDPHandler(socketserver.BaseRequestHandler):293    """294    Этот класс работает аналогично классу-обработчику TCP, за исключением того, что295    self.request состоит из пары данных и клиентского сокета, и поскольку296    соединение отсутствует, адрес клиента должен быть указан явно297    при отправке данных обратно через sendto().298    """299300    def handle(self):301        data = self.request[0].strip()302        socket = self.request[1]303        print("{} wrote:".format(self.client_address[0]))304        print(data)305        socket.sendto(data.upper(), self.client_address)306307if __name__ == "__main__":308    HOST, PORT = "localhost", 9999309    server = socketserver.UDPServer((HOST, PORT), MyUDPHandler)310    server.serve_forever()311```312313Это клиентская сторона:314315```python316import socket317import sys318319HOST, PORT = "localhost", 9999320data = " ".join(sys.argv[1:])321322# SOCK_DGRAM – это тип сокета для UDP-сокетов323sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)324325# Как можно видеть, вызов connect() отсутствует; в UDP нет соединений.326# Вместо этого данные отправляются напрямую получателю через sendto().327sock.sendto(bytes(data + "\n", "utf-8"), (HOST, PORT))328received = str(sock.recv(1024), "utf-8")329330print("Sent:     {}".format(data))331print("Received: {}".format(received))332```333334Результат работы примера должен выглядеть точно так же, как для примера TCP-сервера.335336### 21.21.4.3. Асинхронные миксины337338Для создания асинхронных обработчиков используйте классы `ThreadingMixIn` и `ForkingMixIn`.339340Пример для класса `ThreadingMixIn`:341342```python343import socket344import threading345import socketserver346347class ThreadedTCPRequestHandler(socketserver.BaseRequestHandler):348349    def handle(self):350        data = str(self.request.recv(1024), 'ascii')351        cur_thread = threading.current_thread()352        response = bytes("{}: {}".format(cur_thread.name, data), 'ascii')353        self.request.sendall(response)354355class ThreadedTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):356    pass357358def client(ip, port, message):359    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)360    sock.connect((ip, port))361    try:362        sock.sendall(bytes(message, 'ascii'))363        response = str(sock.recv(1024), 'ascii')364        print("Received: {}".format(response))365    finally:366        sock.close()367368if __name__ == "__main__":369    # Порт 0 означает выбор произвольного неиспользуемого порта370    HOST, PORT = "localhost", 0371372    server = ThreadedTCPServer((HOST, PORT), ThreadedTCPRequestHandler)373    ip, port = server.server_address374375    # Запустить поток для сервера – этот поток затем запустит один376    # дополнительный поток на каждый запрос377    server_thread = threading.Thread(target=server.serve_forever)378    # Завершить поток сервера при завершении главного потока379    server_thread.daemon = True380    server_thread.start()381    print("Server loop running in thread:", server_thread.name)382383    client(ip, port, "Hello World 1")384    client(ip, port, "Hello World 2")385    client(ip, port, "Hello World 3")386387    server.shutdown()388```389390Результат работы примера должен выглядеть примерно так:391392```python393$ python ThreadedTCPServer.py394Server loop running in thread: Thread-1395Received: Thread-2: Hello World 1396Received: Thread-3: Hello World 2397Received: Thread-4: Hello World 3398```399400Класс `ForkingMixIn` используется так же, за исключением того, что сервер будет создавать новый процесс для каждого запроса.401