From bf4a6b8cae4de50750dd2b4aa1181a937c69620a Mon Sep 17 00:00:00 2001 From: Manav | Software Developer Date: Sat, 14 Nov 2026 07:27:23 +0530 Subject: [PATCH] Document attrs choices in the contributor guide --- docs/source/contributing.rst | 71 ++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 63b4ff408e..7cfada2b3c 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -307,6 +307,77 @@ worth it! And don't be afraid to ask for help. Sometimes a fresh pair of eyes can be helpful when trying to come up with devious tricks. +.. _contributor-attrs: + +Using attrs +~~~~~~~~~~~ + +Trio uses `attrs `__ to define many of its classes. +It generates methods such as ``__init__`` and ``__repr__`` from annotated +fields, while letting each class choose its equality and mutability behavior. +When changing a class, keep those choices in mind rather than copying the +nearest decorator unchanged. + +Private fields and constructor arguments +++++++++++++++++++++++++++++++++++++++++ + +Use a leading underscore for implementation details that callers should not +access directly. If such a field is an argument to a public constructor, +provide an explicit ``alias`` without the underscore:: + + import attrs + + @attrs.define(eq=False) + class Example: + _name: str = attrs.field(alias="name") + _items: list[str] = attrs.field(factory=list, init=False) + + example = Example(name="worker") + +attrs automatically strips leading underscores in constructor arguments, but +Pyright does not infer that transformation without the explicit alias. +For example, :class:`trio.lowlevel.RunVar` uses aliases for its private fields +so that its public constructor accepts ``name`` and ``default``. Fields with +``init=False`` are not constructor arguments and do not need aliases for this +purpose. The ``test_pyright_recognizes_init_attributes`` export test checks +this for publicly constructible attrs classes when run with the +``_trio_check_attrs_aliases`` pytest plugin used in CI. + +See attrs' `private attributes and aliases +`__ +and `Pyright support +`__ for details. + +Equality, slots, and frozen classes ++++++++++++++++++++++++++++++++++++ + +* ``@attrs.define`` normally generates field-based equality. Use ``eq=False`` + for objects that represent distinct identities, such as + :class:`trio.CancelScope` and :class:`trio.lowlevel.Task`. Two cancel scopes + with the same settings are still different scopes. Disabling generated + equality also preserves the base class' hash behavior; do not enable + ``unsafe_hash`` just to make a mutable value object usable as a dictionary + key. + +* ``@attrs.define`` and ``@attrs.frozen`` use slots by default. Keep that + default when the declared fields describe all instance attributes. + ``slots=False`` can be needed when attributes are assigned later without + being declared as fields: for example, ``NurseryManager.__aenter__`` sets + ``_scope`` and ``_nursery``. Also check inheritance and any need to patch + individual instances before changing an existing class' slots setting. + attrs' `slotted classes documentation + `__ describes + the restrictions. + +* Use ``@attrs.frozen`` for records whose fields should not be reassigned, + such as :class:`trio.MemoryChannelStatistics`. This freezes the fields, + not objects stored in them: a list inside a frozen instance can still be + mutated. Stateful objects such as cancel scopes instead need mutable + fields. See the `attrs API reference + `__ for the interaction + between freezing, equality, and hashing. + + .. _pull-request-formatting: Code formatting