docs: style improvements

CHANGELOG.md

@@ -66,7 +66,7 @@ See https://github.com/python-attrs/attrs/blob/main/.github/CONTRIBUTING.md#chan
   [#1068](https://github.com/python-attrs/attrs/issues/1068)
 - `attrs.has()` and `attrs.fields()` now handle generic classes correctly.
   [#1079](https://github.com/python-attrs/attrs/issues/1079)
-- Fix frozen exception classes when raised within e.g. `contextlib.contextmanager`, which mutates their `__traceback__` attributes.
+- Fix frozen exception classes when raised within, for example, `contextlib.contextmanager`, which mutates their `__traceback__` attributes.
   [#1081](https://github.com/python-attrs/attrs/issues/1081)
 - `@frozen` now works with type checkers that implement [PEP-681](https://peps.python.org/pep-0681/) (ex. [pyright](https://github.com/microsoft/pyright/)).
   [#1084](https://github.com/python-attrs/attrs/issues/1084)
@@ -113,7 +113,7 @@ See https://github.com/python-attrs/attrs/blob/main/.github/CONTRIBUTING.md#chan
   Get `__init__` signatures matching any taste, peculiar or plain!
   The [PEP 681 compatible](https://peps.python.org/pep-0681/#field-specifier-parameters) *alias* option can be use to override private attribute name mangling, or add other arbitrary field argument name overrides.
   [#950](https://github.com/python-attrs/attrs/issues/950)
-- `attrs.NOTHING` is now an enum value, making it possible to use with e.g. [`typing.Literal`](https://docs.python.org/3/library/typing.html#typing.Literal).
+- `attrs.NOTHING` is now an enum value, making it possible to use with, for example, [`typing.Literal`](https://docs.python.org/3/library/typing.html#typing.Literal).
   [#983](https://github.com/python-attrs/attrs/issues/983)
 - Added missing re-import of `attr.AttrsInstance` to the `attrs` namespace.
   [#987](https://github.com/python-attrs/attrs/issues/987)
@@ -195,7 +195,7 @@ See https://github.com/python-attrs/attrs/blob/main/.github/CONTRIBUTING.md#chan
 ### Backward-incompatible Changes
 
 - When using `@define`, converters are now run by default when setting an attribute on an instance -- additionally to validators.
-  I.e. the new default is `on_setattr=[attrs.setters.convert, attrs.setters.validate]`.
+  Meaning: the new default is `on_setattr=[attrs.setters.convert, attrs.setters.validate]`.
 
   This is unfortunately a breaking change, but it was an oversight, impossible to raise a `DeprecationWarning` about, and it's better to fix it now while the APIs are very fresh with few users.
   [#835](https://github.com/python-attrs/attrs/issues/835),
@@ -494,7 +494,7 @@ See https://github.com/python-attrs/attrs/blob/main/.github/CONTRIBUTING.md#chan
 
 - `attrs` can now automatically detect your own implementations and infer `init=False`, `repr=False`, `eq=False`, `order=False`, and `hash=False` if you set `@attr.s(auto_detect=True)`.
   `attrs` will ignore inherited methods.
-  If the argument implies more than one method (e.g. `eq=True` creates both `__eq__` and `__ne__`), it's enough for *one* of them to exist and `attrs` will create *neither*.
+  If the argument implies more than one method (for example, `eq=True` creates both `__eq__` and `__ne__`), it's enough for *one* of them to exist and `attrs` will create *neither*.
 
   This feature requires Python 3.
   [#607](https://github.com/python-attrs/attrs/issues/607)
@@ -727,7 +727,7 @@ See https://github.com/python-attrs/attrs/blob/main/.github/CONTRIBUTING.md#chan
   [#290](https://github.com/python-attrs/attrs/issues/290),
   [#349](https://github.com/python-attrs/attrs/issues/349)
 
-- The order of attributes that are passed into `attr.make_class()` or the *these* argument of `@attr.s()` is now retained if the dictionary is ordered (i.e. `dict` on Python 3.6 and later, `collections.OrderedDict` otherwise).
+- The order of attributes that are passed into `attr.make_class()` or the *these* argument of `@attr.s()` is now retained if the dictionary is ordered (in other words: `dict` on Python 3.6 and later, `collections.OrderedDict` otherwise).
 
   Before, the order was always determined by the order in which the attributes have been defined which may not be desirable when creating classes programmatically.
 
@@ -1105,7 +1105,7 @@ To encourage more participation, the project has also been moved into a [dedicat
 ### Changes:
 
 - Added a `convert` argument to `attr.ib`, which allows specifying a function to run on arguments.
-  This allows for simple type conversions, e.g. with `attr.ib(convert=int)`.
+  This allows for simple type conversions, for example, with `attr.ib(convert=int)`.
   [#26](https://github.com/python-attrs/attrs/issues/26)
 - Speed up object creation when attribute validators are used.
   [#28](https://github.com/python-attrs/attrs/issues/28)

conftest.py

@@ -6,7 +6,7 @@
 
 from hypothesis import HealthCheck, settings
 
-from attr._compat import PY310
+from attr._compat import PY_3_10_PLUS
 
 
 @pytest.fixture(name="slots", params=(True, False))
@@ -32,5 +32,5 @@ def pytest_configure(config):
 
 
 collect_ignore = []
-if not PY310:
+if not PY_3_10_PLUS:
     collect_ignore.extend(["tests/test_pattern_matching.py"])

docs/api.rst

@@ -11,7 +11,7 @@ If you're confused by the many names, please check out `names` for clarification
 
 - The classic ``attr`` that powers the venerable `attr.s` and `attr.ib`.
 - The newer ``attrs`` that only contains most modern APIs and relies on `attrs.define` and `attrs.field` to define your classes.
-  Additionally it offers some ``attr`` APIs with nicer defaults (e.g. `attrs.asdict`).
+  Additionally it offers some ``attr`` APIs with nicer defaults (for example, `attrs.asdict`).
 
 The ``attrs`` namespace is built *on top of* ``attr`` -- which will *never* go away -- and is just as stable, since it doesn't constitute a rewrite.
 To keep repetition low and this document at a reasonable size, the ``attr`` namespace is `documented on a separate page <api-attr>`, though.

docs/examples.md

@@ -569,7 +569,7 @@ AutoC(l=[], x=1, foo='every attrib needs a type if auto_attribs=True', bar=None)
 
 The generated `__init__` method will have an attribute called `__annotations__` that contains this type information.
 
-If your annotations contain strings (e.g. forward references),
+If your annotations contain strings (for example, forward references),
 you can resolve these after all references have been defined by using {func}`attrs.resolve_types`.
 This will replace the *type* attribute in the respective fields.
 

docs/extending.md

@@ -214,7 +214,7 @@ For example, let's assume that you really don't like floats:
 Data(a=42, c='spam')
 ```
 
-A more realistic example would be to automatically convert data that you, e.g., load from JSON:
+A more realistic example would be to automatically convert data that you, for example, load from JSON:
 
 ```{doctest}
 >>> from datetime import datetime

docs/how-does-it-work.md

@@ -64,7 +64,7 @@ Once constructed, frozen instances don't differ in any way from regular ones exc
 
 ### 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).
+Dict classes -- that is: 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.
 
@@ -95,9 +95,9 @@ Pick what's more important to you.
 
 ### Summary
 
-You should avoid instantiating lots of frozen slotted classes (i.e. `@frozen`) in performance-critical code.
+You should avoid instantiating lots of frozen slotted classes (meaning: `@frozen`) in performance-critical code.
 
-Frozen dict classes have barely a performance impact, unfrozen slotted classes are even *faster* than unfrozen dict classes (i.e. regular classes).
+Frozen dict classes have barely a performance impact, unfrozen slotted classes are even *faster* than unfrozen dict classes (meaning: regular classes).
 
 
 (how-slotted-cached_property)=

docs/init.md

@@ -370,7 +370,7 @@ For that purpose, *attrs* offers the following options:
 - `__attrs_post_init__` is automatically detected and run *after* *attrs* is done initializing your instance.
   This is useful if you want to derive some attribute from others or perform some kind of validation over the whole instance.
 
-- `__attrs_init__` is written and attached to your class *instead* of `__init__`, if *attrs* is told to not write one (i.e. `init=False` or a combination of `auto_detect=True` and a custom `__init__`).
+- `__attrs_init__` is written and attached to your class *instead* of `__init__`, if *attrs* is told to not write one (when `init=False` or a by a combination of `auto_detect=True` and a custom `__init__`).
   This is useful if you want full control over the initialization process, but don't want to set the attributes by hand.
 
 

src/attr/_cmp.py

@@ -26,21 +26,21 @@ def cmp_using(
     The resulting class will have a full set of ordering methods if at least
     one of ``{lt, le, gt, ge}`` and ``eq``  are provided.
 
-    :param Optional[callable] eq: `callable` used to evaluate equality of two
+    :param typing.Callable | None eq: `Callable` used to evaluate equality of two
         objects.
-    :param Optional[callable] lt: `callable` used to evaluate whether one
+    :param typing.Callable | None lt: `Callable` used to evaluate whether one
         object is less than another object.
-    :param Optional[callable] le: `callable` used to evaluate whether one
+    :param typing.Callable | None le: `Callable` used to evaluate whether one
         object is less than or equal to another object.
-    :param Optional[callable] gt: `callable` used to evaluate whether one
+    :param typing.Callable | None gt: `Callable` used to evaluate whether one
         object is greater than another object.
-    :param Optional[callable] ge: `callable` used to evaluate whether one
+    :param typing.Callable | None ge: `Callable` used to evaluate whether one
         object is greater than or equal to another object.
 
     :param bool require_same_type: When `True`, equality and ordering methods
         will return `NotImplemented` if objects are not of the same type.
 
-    :param Optional[str] class_name: Name of class. Defaults to 'Comparable'.
+    :param str | None class_name: Name of class. Defaults to "Comparable".
 
     See `comparison` for more details.
 

src/attr/_compat.py

@@ -12,7 +12,7 @@
 PYPY = platform.python_implementation() == "PyPy"
 PY_3_8_PLUS = sys.version_info[:2] >= (3, 8)
 PY_3_9_PLUS = sys.version_info[:2] >= (3, 9)
-PY310 = sys.version_info[:2] >= (3, 10)
+PY_3_10_PLUS = sys.version_info[:2] >= (3, 10)
 PY_3_12_PLUS = sys.version_info[:2] >= (3, 12)
 PY_3_13_PLUS = sys.version_info[:2] >= (3, 13)
 

src/attr/_funcs.py

@@ -432,25 +432,25 @@ def resolve_types(
     Resolve any strings and forward annotations in type annotations.
 
     This is only required if you need concrete types in `Attribute`'s *type*
-    field. In other words, you don't need to resolve your types if you only
-    use them for static type checking.
+    field. In other words, you don't need to resolve your types if you only use
+    them for static type checking.
 
     With no arguments, names will be looked up in the module in which the class
-    was created. If this is not what you want, e.g. if the name only exists
-    inside a method, you may pass *globalns* or *localns* to specify other
-    dictionaries in which to look up these names. See the docs of
+    was created. If this is not what you want, for example, if the name only
+    exists inside a method, you may pass *globalns* or *localns* to specify
+    other dictionaries in which to look up these names. See the docs of
     `typing.get_type_hints` for more details.
 
     :param type cls: Class to resolve.
-    :param Optional[dict] globalns: Dictionary containing global variables.
-    :param Optional[dict] localns: Dictionary containing local variables.
-    :param Optional[list] attribs: List of attribs for the given class.
-        This is necessary when calling from inside a ``field_transformer``
-        since *cls* is not an *attrs* class yet.
-    :param bool include_extras: Resolve more accurately, if possible.
-        Pass ``include_extras`` to ``typing.get_hints``, if supported by the
-        typing module. On supported Python versions (3.9+), this resolves the
-        types more accurately.
+    :param dict | None globalns: Dictionary containing global variables.
+    :param dict | None localns: Dictionary containing local variables.
+    :param list | None attribs: List of attribs for the given class. This is
+        necessary when calling from inside a ``field_transformer`` since *cls*
+        is not an *attrs* class yet.
+    :param bool include_extras: Resolve more accurately, if possible. Pass
+        ``include_extras`` to ``typing.get_hints``, if supported by the typing
+        module. On supported Python versions (3.9+), this resolves the types
+        more accurately.
 
     :raise TypeError: If *cls* is not a class.
     :raise attrs.exceptions.NotAnAttrsClassError: If *cls* is not an *attrs*
@@ -464,7 +464,6 @@ class and you didn't pass any attribs.
     ..  versionadded:: 20.1.0
     ..  versionadded:: 21.1.0 *attribs*
     ..  versionadded:: 23.1.0 *include_extras*
-
     """
     # Since calling get_type_hints is expensive we cache whether we've
     # done it already.