From caaf98a26c357fb353a70fd3f88226b70da08cf7 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Thu, 25 Feb 2021 08:40:24 +0100 Subject: [PATCH 1/9] Document comparison --- docs/comparison.rst | 36 ++++++++++++++++++++++++++++++++++++ docs/index.rst | 3 +++ 2 files changed, 39 insertions(+) create mode 100644 docs/comparison.rst diff --git a/docs/comparison.rst b/docs/comparison.rst new file mode 100644 index 000000000..2302a3ce6 --- /dev/null +++ b/docs/comparison.rst @@ -0,0 +1,36 @@ +Comparison +========== + +By default, two instances of ``attrs`` classes is equal, if all their fields are equal. +For that, ``attrs`` writes ``__eq__`` and ``__ne__`` methods for you. + +Additionally, if you pass ``order=True`` (default if you use the `attr.s` decorator), ``attrs`` will also create a full set of ordering methods that are based on the defined attributes: ``__le__``, ``__lt__``, ``__ge__``, and ``__gt__``. + + +Customization +------------- + +As with other features, you can exclude attributes from being involved in comparison operations: + +.. doctest:: + + >>> import attr + >>> @attr.s + ... class C(object): + ... x = attr.ib() + ... y = attr.ib(eq=False) + >>> C(1, 2) == C(1, 3) + True + +Additionally you can also pass a *callable* instead of a bool to both ``eq`` and ``order``. +It is then used as a key function like you may know from `sorted`: + + >>> import attr + >>> @attr.s + ... class C(object): + ... x = attr.ib(order=int) + >>> C("10") > C("2") + True + +This is especially useful when you have fields with objects that have untypical comparison properties. +A common example being `NumPy arrays `_. diff --git a/docs/index.rst b/docs/index.rst index 70ef6c109..2700045ef 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -41,6 +41,8 @@ Day-to-Day Usage - Instance initialization is one of ``attrs`` key feature areas. Our goal is to relieve you from writing as much code as possible. `init` gives you an overview what ``attrs`` has to offer and explains some related philosophies we believe in. +- Comparing and ordering objects is a common task. + `comparison` shows you how ``attrs`` helps you with that and how you can customize it. - If you want to put objects into sets or use them as keys in dictionaries, they have to be hashable. The simplest way to do that is to use frozen classes, but the topic is more complex than it seems and `hashing` will give you a primer on what to look out for. - Once you're comfortable with the concepts, our `api` contains all information you need to use ``attrs`` to its fullest. @@ -67,6 +69,7 @@ Full Table of Contents examples types init + comparison hashing api extending From 2509889f4b59ad521843114aefcc6f0bd47e0ba3 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Thu, 25 Feb 2021 12:59:28 +0100 Subject: [PATCH 2/9] Grammar --- docs/comparison.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/comparison.rst b/docs/comparison.rst index 2302a3ce6..a0922c8de 100644 --- a/docs/comparison.rst +++ b/docs/comparison.rst @@ -1,7 +1,7 @@ Comparison ========== -By default, two instances of ``attrs`` classes is equal, if all their fields are equal. +By default, two instances of ``attrs`` classes are equal, if all their fields are equal. For that, ``attrs`` writes ``__eq__`` and ``__ne__`` methods for you. Additionally, if you pass ``order=True`` (default if you use the `attr.s` decorator), ``attrs`` will also create a full set of ordering methods that are based on the defined attributes: ``__le__``, ``__lt__``, ``__ge__``, and ``__gt__``. From b8d96609a551022f0cbfe12f92df9f864ebd1c9a Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Thu, 25 Feb 2021 13:03:27 +0100 Subject: [PATCH 3/9] Stress independence of eq/order --- docs/comparison.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/comparison.rst b/docs/comparison.rst index a0922c8de..2b9658dc7 100644 --- a/docs/comparison.rst +++ b/docs/comparison.rst @@ -22,9 +22,11 @@ As with other features, you can exclude attributes from being involved in compar >>> C(1, 2) == C(1, 3) True -Additionally you can also pass a *callable* instead of a bool to both ``eq`` and ``order``. +Additionally you can also pass a *callable* instead of a bool to both ``eq`` and ``order`` It is then used as a key function like you may know from `sorted`: +.. doctest:: + >>> import attr >>> @attr.s ... class C(object): @@ -34,3 +36,5 @@ It is then used as a key function like you may know from `sorted`: This is especially useful when you have fields with objects that have untypical comparison properties. A common example being `NumPy arrays `_. + +Please note that they are set *independently* because *order* is `False` by default in `modern APIs `. From 1967f0461aae9ba551ac6ac1d7ae253cf61baf62 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Thu, 25 Feb 2021 13:07:12 +0100 Subject: [PATCH 4/9] Add example for eq --- docs/comparison.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/comparison.rst b/docs/comparison.rst index 2b9658dc7..2c357e07c 100644 --- a/docs/comparison.rst +++ b/docs/comparison.rst @@ -22,13 +22,18 @@ As with other features, you can exclude attributes from being involved in compar >>> C(1, 2) == C(1, 3) True -Additionally you can also pass a *callable* instead of a bool to both ``eq`` and ``order`` +Additionally you can also pass a *callable* instead of a bool to both *eq* and *order*. It is then used as a key function like you may know from `sorted`: .. doctest:: >>> import attr >>> @attr.s + ... class S(object): + ... x = attr.ib(eq=str.lower) + >>> S("foo") == S("FOO") + True + >>> @attr.s ... class C(object): ... x = attr.ib(order=int) >>> C("10") > C("2") From cabf607e8240761b08d5a96bc8b6f00bb1d47c66 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Thu, 25 Feb 2021 13:10:04 +0100 Subject: [PATCH 5/9] Be consistent with fields --- docs/comparison.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/comparison.rst b/docs/comparison.rst index 2c357e07c..573b5e0f3 100644 --- a/docs/comparison.rst +++ b/docs/comparison.rst @@ -4,13 +4,13 @@ Comparison By default, two instances of ``attrs`` classes are equal, if all their fields are equal. For that, ``attrs`` writes ``__eq__`` and ``__ne__`` methods for you. -Additionally, if you pass ``order=True`` (default if you use the `attr.s` decorator), ``attrs`` will also create a full set of ordering methods that are based on the defined attributes: ``__le__``, ``__lt__``, ``__ge__``, and ``__gt__``. +Additionally, if you pass ``order=True`` (which is the default if you use the `attr.s` decorator), ``attrs`` will also create a full set of ordering methods that are based on the defined fields: ``__le__``, ``__lt__``, ``__ge__``, and ``__gt__``. Customization ------------- -As with other features, you can exclude attributes from being involved in comparison operations: +As with other features, you can exclude fields from being involved in comparison operations: .. doctest:: From 026edd24f07aa168edc0efa4b7ab4e198889bc11 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Fri, 26 Feb 2021 07:42:03 +0100 Subject: [PATCH 6/9] Update docs/comparison.rst Co-authored-by: Julian Berman --- docs/comparison.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/comparison.rst b/docs/comparison.rst index 573b5e0f3..30cbbfcc2 100644 --- a/docs/comparison.rst +++ b/docs/comparison.rst @@ -1,7 +1,7 @@ Comparison ========== -By default, two instances of ``attrs`` classes are equal, if all their fields are equal. +By default, two instances of ``attrs`` classes are equal if all their fields are equal. For that, ``attrs`` writes ``__eq__`` and ``__ne__`` methods for you. Additionally, if you pass ``order=True`` (which is the default if you use the `attr.s` decorator), ``attrs`` will also create a full set of ordering methods that are based on the defined fields: ``__le__``, ``__lt__``, ``__ge__``, and ``__gt__``. From 6385d90b44a9aae08b777cd927c3aa2cbc80578b Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Fri, 26 Feb 2021 07:42:14 +0100 Subject: [PATCH 7/9] Update docs/comparison.rst Co-authored-by: Julian Berman --- docs/comparison.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/comparison.rst b/docs/comparison.rst index 30cbbfcc2..67fce08a5 100644 --- a/docs/comparison.rst +++ b/docs/comparison.rst @@ -39,7 +39,7 @@ It is then used as a key function like you may know from `sorted`: >>> C("10") > C("2") True -This is especially useful when you have fields with objects that have untypical comparison properties. +This is especially useful when you have fields with objects that have atypical comparison properties. A common example being `NumPy arrays `_. Please note that they are set *independently* because *order* is `False` by default in `modern APIs `. From d91dbb45028c16becb524f0354dcfe1a672dc185 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Fri, 26 Feb 2021 07:42:23 +0100 Subject: [PATCH 8/9] Update docs/comparison.rst Co-authored-by: Julian Berman --- docs/comparison.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/comparison.rst b/docs/comparison.rst index 67fce08a5..0fde9e290 100644 --- a/docs/comparison.rst +++ b/docs/comparison.rst @@ -40,6 +40,6 @@ It is then used as a key function like you may know from `sorted`: True This is especially useful when you have fields with objects that have atypical comparison properties. -A common example being `NumPy arrays `_. +Common examples of such objects are `NumPy arrays `_. Please note that they are set *independently* because *order* is `False` by default in `modern APIs `. From 41c9a9c15f8789b184863cf36eca85426a4248ac Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Fri, 26 Feb 2021 07:44:46 +0100 Subject: [PATCH 9/9] Clarify --- docs/comparison.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/comparison.rst b/docs/comparison.rst index 0fde9e290..37b422272 100644 --- a/docs/comparison.rst +++ b/docs/comparison.rst @@ -42,4 +42,4 @@ It is then used as a key function like you may know from `sorted`: This is especially useful when you have fields with objects that have atypical comparison properties. Common examples of such objects are `NumPy arrays `_. -Please note that they are set *independently* because *order* is `False` by default in `modern APIs `. +Please note that *eq* and *order* are set *independently*, because *order* is `False` by default in `modern APIs `.