diff --git a/content/python/concepts/functools-module/terms/total-ordering/total-ordering.md b/content/python/concepts/functools-module/terms/total-ordering/total-ordering.md new file mode 100644 index 00000000000..afbed3a2abd --- /dev/null +++ b/content/python/concepts/functools-module/terms/total-ordering/total-ordering.md @@ -0,0 +1,131 @@ +--- +Title: 'total_ordering()' +Description: 'Generates missing comparison methods in a class based on a minimal set of defined ones.' +Subjects: + - 'Code Foundations' + - 'Computer Science' +Tags: + - 'Classes' + - 'Modules' + - 'Python' +CatalogContent: + - 'learn-python-3' + - 'paths/computer-science' +--- + +In Python, the **`total_ordering()`** decorator from the `functools` module simplifies the creation of fully ordered classes. By defining the `__eq__()` method and one additional comparison method (`__lt__()`, `__le__()`, `__gt__()`, or `__ge__()`), all other rich comparison methods are automatically generated. + +This decorator reduces redundant code in custom classes that require complete ordering behavior for comparisons, sorting, and equality checks. + +## Syntax + +```pseudo +from functools import total_ordering + +@total_ordering +class ClassName: + def __eq__(self, other): ... + def __lt__(self, other): ... +``` + +**Parameters:** + +The `total_ordering()` decorator takes no parameters. + +**Return value:** + +Returns a class with the missing comparison methods (`__le__`, `__gt__`, and `__ge__`) automatically added. + +## Example 1: Numeric Wrapper Class + +The following example defines a class that compares wrapped numeric values. Only `__eq__()` and `__lt__()` are implemented; the rest are generated automatically: + +```py +from functools import total_ordering + +@total_ordering +class Number: + def __init__(self, value): + self.value = value + + def __eq__(self, other): + return self.value == other.value + + def __lt__(self, other): + return self.value < other.value + +print(Number(3) < Number(4)) +print(Number(5) >= Number(5)) +print(Number(7) > Number(1)) +``` + +The outout of this code is: + +```shell +True +True +True +``` + +## Example 2: Ordering Strings by Length + +This example demonstrates ordering based on string length instead of direct string comparison: + +```py +from functools import total_ordering + +@total_ordering +class Word: + def __init__(self, text): + self.text = text + + def __eq__(self, other): + return len(self.text) == len(other.text) + + def __lt__(self, other): + return len(self.text) < len(other.text) + +print(Word("apple") < Word("banana")) +print(Word("kiwi") == Word("pear")) +print(Word("grape") > Word("fig")) +``` + +The output of this code is: + +```shell +True +True +True +``` + +## Codebyte Example: Prioritizing Tasks + +The following codebyte defines a class where objects are ordered by priority value: + +```codebyte/python +from functools import total_ordering + +@total_ordering +class Task: + def __init__(self, name, priority): + self.name = name + self.priority = priority + + def __eq__(self, other): + return self.priority == other.priority + + def __lt__(self, other): + return self.priority > other.priority + +tasks = [ + Task("Write report", 2), + Task("Fix bugs", 5), + Task("Plan sprint", 3) +] + +tasks.sort() +for t in tasks: + print(t.name, t.priority) +``` + +Higher priority numbers are treated as greater for sorting purposes.