Skip to content

docs(conventions): settle the member-order page wording and align the protocol registry with the other maps (#2772, #2773) #2779

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

Merged
JarryShaw merged 2 commits into from
Nov 4, 2026
Merged

docs(conventions): settle the member-order page wording and align the protocol registry with the other maps (#2772, #2773) #2779

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2dc03c4
docs(conventions): settle the member-order page wording and align the…
JarryShaw Nov 4, 2026
7cc8cfd
docs(registry): plain-sentence _release_name docstring; pin the name …
JarryShaw Nov 4, 2026
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
29 changes: 21 additions & 8 deletions docs/source/contributing/conventions/protocol-member-order.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,24 +38,37 @@ The Order
``_read_opt_unassigned()`` opens the readers of
:class:`~pcapkit.protocols.internet.ipv4.protocol.IPv4`; the rest follow the enum value
of the code or type each handles, not alphabetical order. Ruled on
:issue:`2490`.
:issue:`2490`. A class with several registries puts every registry's readers
before any registry's makers, as :class:`~pcapkit.protocols.internet.mh.protocol.MH`
and :class:`~pcapkit.protocols.misc.pcapng.protocol.PCAPNG` do, ruled on
:issue:`2772`.
d. **Other helpers.** Every helper that ``read()``, ``make()`` and the registries
do not reach goes last, including one that only another helper calls, such as
``_decode_text()`` in :class:`~pcapkit.protocols.application.httpv1.protocol.HTTPv1`.
Ruled on :issue:`2490`.

**Registry maps.** The registry maps themselves (``__proto__``, ``__option__``,
``__parameter__`` and similar) are ordered by their enum values, or alphabetically
by key where there is no enum.
``__parameter__`` and similar) are ordered by their enum values, by key value where
an :class:`int` key has no enum, and alphabetically where the key is a string, as the
namespaces of
:attr:`Option.__enum__ <pcapkit.protocols.misc.pcapng.schema.Option.__enum__>` are.
:attr:`PCAPNG.__option__ <pcapkit.protocols.misc.pcapng.protocol.PCAPNG.__option__>`,
keyed by an option's namespace and value, is ordered by namespace, in the order
:class:`~pcapkit.const.pcapng.option_type.OptionType` declares them, then by value.
Ruled on :issue:`2772`.
:attr:`ProtocolBase.__registry__ <pcapkit.protocols.protocol.ProtocolBase.__registry__>`
groups its built-in entries by layer under the comments ``# Link Layer``,
``# Internet Layer``, ``# Transport Layer``, ``# Application Layer`` and
``# Miscellaneous``, in that order, the last holding what belongs to no layer, and
is alphabetical within each group, ruled on :issue:`2773`.

**The guard.** :file:`tests/project/test_protocol_member_order_2490_unit.py` holds
every protocol class to the groups, ``_make_data()`` first, each ``_read_xxx()``
before its ``_make_xxx()``, subgroups b, c and d, and the order of the registry
maps, with a table of known exceptions (:issue:`2490`). It values a key that is an
enum member or an :class:`int`; a map with a key of another shape, such as the
computed keys of
:attr:`PCAPNG.__option__ <pcapkit.protocols.misc.pcapng.protocol.PCAPNG.__option__>`,
it leaves in its own order, which rule c then follows.
maps, layer groups included, with a table of known exceptions (:issue:`2490`). It
values a key that is an enum member, an :class:`int`, a string or a PCAP-NG option
key, and orders a string-keyed map within each group its comment lines open; a map
with a key of another shape it leaves in its own order, which rule c then follows.

Example
~~~~~~~
Expand Down
10 changes: 5 additions & 5 deletions docs/source/pcapkit/protocols/application/application.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,13 @@ which is a base class for application layer protocols, e.g.
:no-members:
:show-inheritance:

.. autoproperty:: layer

.. automethod:: _decode_next_layer
.. automethod:: _import_next_layer

.. autoattribute:: __layer__
:no-value:

.. autoproperty:: layer

.. automethod:: __post_init__
.. automethod:: __index__

.. automethod:: _decode_next_layer
.. automethod:: _import_next_layer
13 changes: 5 additions & 8 deletions docs/source/pcapkit/protocols/application/http.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,29 +37,26 @@ which tells whether a payload opens with an HTTP/1.* start line.
:no-members:
:show-inheritance:

.. autoattribute:: _preface_length

.. autoproperty:: name
.. autoproperty:: alias
.. autoproperty:: length
.. autoproperty:: version

.. automethod:: id

.. automethod:: read
.. automethod:: make

.. automethod:: _make_data
.. automethod:: from_data

.. automethod:: __index__
.. automethod:: __init__
.. automethod:: __new__

.. automethod:: _make_data
.. automethod:: _guess_version
.. automethod:: _dispatch_version
.. automethod:: _member_of_version

.. autoattribute:: _preface_length

.. automethod:: from_data
.. automethod:: _dispatch_version

.. autofunction:: pcapkit.protocols.application.http.protocol.test_start_line

Expand Down
4 changes: 1 addition & 3 deletions docs/source/pcapkit/protocols/application/httpv1.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,13 +51,11 @@ structure of an HTTP/1.* message is described as below:
.. autoproperty:: alias
.. autoproperty:: version

.. automethod:: id

.. automethod:: read
.. automethod:: make
.. automethod:: id

.. automethod:: _make_data

.. automethod:: _read_http_header
.. automethod:: _read_http_body

Expand Down
16 changes: 6 additions & 10 deletions docs/source/pcapkit/protocols/application/httpv2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,18 +66,20 @@ exceptions:
:no-members:
:show-inheritance:

.. autoattribute:: __frame__
:no-value:

.. autoproperty:: alias
.. autoproperty:: length
.. autoproperty:: version

.. automethod:: id
.. automethod:: register_frame

.. automethod:: unpack
.. automethod:: read
.. automethod:: make
.. automethod:: id
.. automethod:: register_frame

.. automethod:: _make_data

.. automethod:: _read_http_none
.. automethod:: _read_http_data
.. automethod:: _read_http_headers
Expand All @@ -89,7 +91,6 @@ exceptions:
.. automethod:: _read_http_goaway
.. automethod:: _read_http_window_update
.. automethod:: _read_http_continuation

.. automethod:: _make_http_none
.. automethod:: _make_http_data
.. automethod:: _make_http_headers
Expand All @@ -102,11 +103,6 @@ exceptions:
.. automethod:: _make_http_window_update
.. automethod:: _make_http_continuation

.. autoattribute:: __frame__
:no-value:

.. automethod:: unpack

Header Schemas
--------------

Expand Down
6 changes: 2 additions & 4 deletions docs/source/pcapkit/protocols/application/ospf.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,13 +72,11 @@ as below:
.. automethod:: read
.. automethod:: make

.. automethod:: _make_data
.. automethod:: __index__

.. automethod:: _make_data
.. automethod:: _read_encrypt_auth
.. automethod:: _make_encrypt_auth

.. automethod:: __index__

.. automethod:: _make_id_numbers

Header Schemas
Expand Down
23 changes: 7 additions & 16 deletions docs/source/pcapkit/protocols/application/ssl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,9 @@ accepting bytes that cannot be a genuine record.
:no-members:
:show-inheritance:

.. autoattribute:: __extension__
:no-value:

.. automethod:: id
.. automethod:: register_extension

Expand All @@ -52,7 +55,6 @@ accepting bytes that cannot be a genuine record.
.. automethod:: _read_ext_supported_versions
.. automethod:: _read_ext_key_share
.. automethod:: _read_ext_connection_id

.. automethod:: _make_ext_unknown
.. automethod:: _make_ext_server_name
.. automethod:: _make_ext_supported_groups
Expand All @@ -61,32 +63,21 @@ accepting bytes that cannot be a genuine record.
.. automethod:: _make_ext_supported_versions
.. automethod:: _make_ext_key_share
.. automethod:: _make_ext_connection_id

.. automethod:: _validate_tls_record

.. automethod:: _tls_content_is_cleartext

.. automethod:: _read_tls_content
.. automethod:: _make_tls_content

.. automethod:: _read_tls_handshake_messages
.. automethod:: _make_tls_handshake_messages

.. automethod:: _read_tls_client_hello
.. automethod:: _make_tls_client_hello

.. automethod:: _read_tls_server_hello
.. automethod:: _make_tls_server_hello

.. automethod:: _read_tls_encrypted_extensions
.. automethod:: _make_tls_encrypted_extensions

.. automethod:: _read_tls_extensions
.. automethod:: _make_tls_content
.. automethod:: _make_tls_client_hello
.. automethod:: _make_tls_server_hello
.. automethod:: _make_tls_encrypted_extensions
.. automethod:: _make_tls_extensions

.. autoattribute:: __extension__
:no-value:

Data Models
-----------

Expand Down
3 changes: 1 addition & 2 deletions docs/source/pcapkit/protocols/application/sslv2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,11 +75,10 @@ a ``CLIENT-MASTER-KEY`` reads ``SSLv2:SSLv2``. The exceptions:
.. autoproperty:: alias
.. autoproperty:: length

.. automethod:: id
.. automethod:: read
.. automethod:: make

.. automethod:: id

.. automethod:: _make_data
.. automethod:: _make_sslv2_client_hello
.. automethod:: _make_sslv2_server_hello
Expand Down
30 changes: 13 additions & 17 deletions docs/source/pcapkit/protocols/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -242,31 +242,27 @@ Header Schema
:no-members:
:show-inheritance:

.. autoattribute:: __fields__
:no-value:

.. autoattribute:: __payload__
.. autoattribute:: __additional__
:no-value:

.. autoattribute:: __excluded__
:no-value:

.. automethod:: __init_subclass__
.. automethod:: __new__

.. automethod:: from_dict
.. automethod:: to_dict
.. automethod:: to_bytes
.. automethod:: get_payload
.. automethod:: pack
.. automethod:: pre_pack

.. automethod:: unpack
.. automethod:: pre_unpack

.. automethod:: post_process
.. automethod:: get_payload

.. automethod:: from_dict
.. automethod:: to_dict
.. automethod:: to_bytes

.. autoattribute:: __fields__
:no-value:

.. automethod:: __init_subclass__
.. automethod:: __new__
.. automethod:: _cut_short_read

.. autoclass:: pcapkit.protocols.schema.EnumSchema
Expand Down Expand Up @@ -339,13 +335,13 @@ Data Model
:members:
:show-inheritance:

.. autoattribute:: __included__
:no-value:

.. autoattribute:: __excluded__
:no-value:

.. seealso::

Please refer to :func:`Protocol._decode_next_layer <pcapkit.protocols.protocol.Protocol._decode_next_layer>`
for more information with the inserted names to be excluded.

.. autoattribute:: __included__
:no-value:
7 changes: 3 additions & 4 deletions docs/source/pcapkit/protocols/internet/ah.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,16 +32,15 @@ Octets Bits Name Description
.. autoproperty:: protocol
.. autoproperty:: protochain

.. automethod:: id

.. automethod:: read
.. automethod:: make

.. automethod:: _make_data
.. automethod:: id

.. automethod:: __post_init__
.. automethod:: __index__

.. automethod:: _make_data

Header Schemas
--------------

Expand Down
18 changes: 9 additions & 9 deletions docs/source/pcapkit/protocols/internet/esp.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,22 +63,21 @@ negotiated out of band. Therefore:

.. autoproperty:: name
.. autoproperty:: alias
.. autoproperty:: length
.. autoproperty:: protocol

.. automethod:: id
.. autoproperty:: length

.. automethod:: read
.. automethod:: make

.. automethod:: _make_data
.. automethod:: _payload_bytes
.. automethod:: _read_trailer
.. automethod:: _make_opaque
.. automethod:: id

.. automethod:: __post_init__
.. automethod:: __index__

.. automethod:: _make_data
.. automethod:: _make_opaque
.. automethod:: _read_trailer
.. automethod:: _payload_bytes

Security Associations
---------------------

Expand Down Expand Up @@ -117,9 +116,10 @@ in :mod:`pcapkit.corekit.context`:
.. automethod:: decrypt
.. automethod:: encrypt

.. automethod:: _split_key
.. automethod:: __repr__

.. automethod:: _split_key

.. autoclass:: pcapkit.protocols.internet.esp.protocol.ESPContext
:no-members:
:show-inheritance:
Expand Down
Loading
Loading