From 58d2adce57f2c4e447eb12b892ebbb09cccbdcc3 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Fri, 26 Feb 2021 07:53:57 +0100 Subject: [PATCH] Document comparison (#768) * Document comparison * Grammar * Stress independence of eq/order * Add example for eq * Be consistent with fields * Update docs/comparison.rst Co-authored-by: Julian Berman * Update docs/comparison.rst Co-authored-by: Julian Berman * Update docs/comparison.rst Co-authored-by: Julian Berman * Clarify Co-authored-by: Julian Berman --- docs/comparison.rst | 45 +++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 3 +++ 2 files changed, 48 insertions(+) create mode 100644 docs/comparison.rst diff --git a/docs/comparison.rst b/docs/comparison.rst new file mode 100644 index 00000000..37b42227 --- /dev/null +++ b/docs/comparison.rst @@ -0,0 +1,45 @@ +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`` (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 fields 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`: + +.. 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") + True + +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 *eq* and *order* are set *independently*, because *order* is `False` by default in `modern APIs `. diff --git a/docs/index.rst b/docs/index.rst index 70ef6c10..2700045e 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