From bfbea3a9018c26c582f6a8daaa3f519a3e734b38 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Sun, 31 Dec 2023 11:34:25 +0100 Subject: [PATCH] docs: wordsmith --- docs/how-does-it-work.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/how-does-it-work.md b/docs/how-does-it-work.md index 7acc81213..72e75eb87 100644 --- a/docs/how-does-it-work.md +++ b/docs/how-does-it-work.md @@ -61,12 +61,14 @@ Depending on whether a class is a dict class or a slotted class, *attrs* uses a Once constructed, frozen instances don't differ in any way from regular ones except that you cannot change its attributes. + ### Dict Classes Dict classes -- i.e. regular classes -- simply assign the value directly into the class' eponymous `__dict__` (and there's nothing we can do to stop the user to do the same). The performance impact is negligible. + ### Slotted Classes Slotted classes are more complicated. @@ -102,17 +104,18 @@ Frozen dict classes have barely a performance impact, unfrozen slotted classes a ## Cached Properties on Slotted Classes. -By default, the standard library `functools.cached_property` decorator does not work on slotted classes, -because it requires a `__dict__` to store the cached value. -This could be surprising when uses *attrs*, as makes using slotted classes so easy, -so attrs will convert `functools.cached_property` decorated methods, when constructing slotted classes. +By default, the standard library `functools.cached_property` decorator does not work on slotted classes, because it requires a `__dict__` to store the cached value. +This could be surprising when using *attrs*, as slotted classes are the default. +Therefore, *attrs* converts `functools.cached_property` decorated methods when constructing slotted classes. Getting this working is achieved by: + * Adding names to `__slots__` for the wrapped methods. * Adding a `__getattr__` method to set values on the wrapped methods. -For most users this should mean that it works transparently. +For most users, this should mean that it works transparently. -Note that the implementation does not guarantee that the wrapped method is called -only once in multi-threaded usage. This matches the implementation of `cached_property` -in python v3.12. +:::{note} +The implementation does not guarantee that the wrapped method is called only once in multi-threaded usage. +This matches the implementation of `cached_property` in Python 3.12. +:::