Skip to content

gh-128319: Add missing server class attributes to socketserver docs #128320

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

gh-128319: Add missing server class attributes to socketserver docs #128320

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a55bfff
Add missing server class attributes to socketserver docs
stephen-hansen Dec 28, 2024
eee013c
fix max_packet_size spacing
stephen-hansen Dec 29, 2024
62c120a
Apply suggested review comments
stephen-hansen Dec 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 29 additions & 7 deletions Doc/library/socketserver.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,12 +264,6 @@ Server Objects
Clean up the server. May be overridden.


.. attribute:: address_family

The family of protocols to which the server's socket belongs.
Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`.


.. attribute:: RequestHandlerClass

The user-provided request handler class; an instance of this class is created
Expand All @@ -294,19 +288,47 @@ Server Objects

.. XXX should class variables be covered before instance variables, or vice versa?

.. attribute:: address_family

The family of protocols to which the server's socket belongs.
Common examples are :const:`socket.AF_INET` and :const:`socket.AF_UNIX`.


.. attribute:: allow_reuse_address

Whether the server will allow the reuse of an address. This defaults to
:const:`False`, and can be set in subclasses to change the policy.


.. attribute:: allow_reuse_port

Whether the server will allow the reuse of a port. This defaults to
:const:`False`, and can be set in subclasses to change the policy.


.. attribute:: max_packet_size

The maximum amount of data (in bytes) to receive at once. If a packet is
too large for the buffer, then the excess bytes beyond :attr:`max_packet_size`
are discarded. The default value is usually ``8192``, but this can be
overridden by subclasses.
Comment on lines +311 to +314
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! With conditions:

Please consider clarifying if the term "data" here, means without IP/UDP headers with something like:

Suggested change
The maximum amount of data (in bytes) to receive at once. If a packet is
too large for the buffer, then the excess bytes beyond :attr:`max_packet_size`
are discarded. The default value is usually ``8192``, but this can be
overridden by subclasses.
The maximum amount of data (in bytes) to receive at once. If a packet's
payload (excluding headers) is too large for the buffer, then the excess
bytes beyond :attr:`max_packet_size` are discarded. The default value
is usually ``8192``, but this can be overridden by subclasses.

or if this really is the literal maximum packet size:

Suggested change
The maximum amount of data (in bytes) to receive at once. If a packet is
too large for the buffer, then the excess bytes beyond :attr:`max_packet_size`
are discarded. The default value is usually ``8192``, but this can be
overridden by subclasses.
The maximum amount of data (in bytes) to receive at once. If a packet's
payload (including headers) is too large for the buffer, then the excess
bytes beyond :attr:`max_packet_size` are discarded. The default value
is usually ``8192``, but this can be overridden by subclasses.

Rational:
Omission of any mention of header when talking about a "packet" being "too large" is somewhat misleading to the reader.
not sure if going further is relevant to the python side, but for convenience sake I'll mention, the typical 20-byte IPV4 header (RFC-791 gives 20-byte base header, 40-byte maximum options) and the required 8-byte header assuming UDP (RFC-768).

Hopefully this helps.

Additional considerations (TL;DR):

  • MTU, and fragmentation boundaries are possible reasons to want to change the default (eg. expected max burst count * max packet size (including headers) on network path with values of 5 * (1500 - 20 - 40 - 8) = 7160 so the default is somewhat larger than the similar stream sockets' request_queue_size default)
  • UDP max packet size (after headers) is a possible (albeit unlikely) reason for increasing the size well beyond the default of 8192


.. note::

Only for datagram sockets, i.e. UDP.


.. attribute:: request_queue_size

The size of the request queue. If it takes a long time to process a single
request, any requests that arrive while the server is busy are placed into a
queue, up to :attr:`request_queue_size` requests. Once the queue is full,
further requests from clients will get a "Connection denied" error. The default
value is usually 5, but this can be overridden by subclasses.
value is usually ``5``, but this can be overridden by subclasses.

.. note::

Only for stream sockets, i.e. TCP.


.. attribute:: socket_type
Expand Down
Loading