From 2a1a02cf1429f7bb95028aaaf505c93809a40d2f Mon Sep 17 00:00:00 2001 From: BethanyG Date: Wed, 20 May 2026 17:49:40 -0700 Subject: [PATCH 1/3] Fix typos and grammer issues as outlined in issue 4165. --- concepts/enums/about.md | 48 ++++++++++++++++++++---------- concepts/enums/introduction.md | 17 +++++++---- concepts/fractions/about.md | 8 ++--- concepts/fractions/introduction.md | 8 ++--- 4 files changed, 51 insertions(+), 30 deletions(-) diff --git a/concepts/enums/about.md b/concepts/enums/about.md index 27b264c22e1..f227372205e 100644 --- a/concepts/enums/about.md +++ b/concepts/enums/about.md @@ -1,14 +1,19 @@ # About -In Python, [an enum][enum-docs] is a set of unique names that are bound unique, **constant** values. Enums are defined by inheriting an `Enum` class. Built-in enum types are available in the module `enum` and the class `Enum` can be imported using `from enum import Enum`. +In Python, [an enum][enum-docs] is a set of unique names that are bound unique, **constant** values. +Enums are defined by inheriting an `Enum` class. +Built-in enum types are available in the module `enum` and the class `Enum` can be imported using `from enum import Enum`. + ```python +from enum import Enum + class Color(Enum): RED = 1 GREEN = 2 ``` -Note that the values of the enum members can be any data types such as str, tuple, float, etc. +Note that the values of the `enum` members can be any data types such as `str`, `tuple`, `float`, etc. ```python class Color(Enum): @@ -16,9 +21,11 @@ class Color(Enum): GREEN = 'green' ``` -Enums can also be created via the following [functional API][enum-functional-api]. +`Enums` can also be created using [function-call syntax][enum-functional-example]. ```python +from enum import Enum + Animal = Enum('Animal', 'ANT BEE CAT DOG') list(Animal) #=> [, , , ] @@ -27,7 +34,7 @@ Animal.ANT.value #=> 1 ``` -When assigning the same value to two members in an enum, the latter assigned member will be an alias to the formed one. It is not allowed to use the same name for two members of an enum. +When assigning the same value to two members in an `enum`, the latter assigned member will be an alias to the former one. It is not allowed to use the same name for two different members of an `enum`. ```python class Color(Enum): @@ -50,12 +57,13 @@ for member in Color: # __members__.items() helps you to loop through alias as well for member in Color.__members__.items(): print(member) -#=>('RED', ) -#=>('GREEN', ) -#=>('ALIAS_OF_RED', ) +#=> ('RED', ) +#=> ('GREEN', ) +#=> ('ALIAS_OF_RED', ) ``` -Enum members can be compared using [`is` (_identity operator_)][identity-keyword] or `is not`. The `==` or `!=` (_equality operators_) work likewise. +`Enum` members can be compared using [`is` (_identity operator_)][identity-keyword] or `is not`. The `==` or `!=` (_equality operators_) work likewise: + ```python a = Color.RED @@ -76,10 +84,10 @@ class Shape(Enum): OVAL = auto() ``` -To disallow aliasing (_preventing duplicate values with different names_), the `@unique` decorator may be used. +To disallow aliasing (_preventing duplicate values with different names_), the [class decorator][class-decorator] [`@enum.unique`][enum-unique-decorator] decorator may be used. ```python -@unique +@enum.unique class Shape(Enum): CIRCLE = 1 SQUARE = 2 @@ -87,7 +95,7 @@ class Shape(Enum): #=> ValueError: duplicate values found in : TRIANGLE -> CIRCLE ``` -To access an enum member for a given value, this notation can be used: `EnumName(value)`. +To access an `enum` member for a given value, this notation can be used: `()`. ```python g = Color(2) @@ -99,15 +107,23 @@ g #=> ``` -A custom [restricted `Enum`][restricted-enums] can be written by subclassing `Enum` with any mix-in or data-type. For example: +A custom [restricted `Enum`][restricted-enums] can be written by subclassing the `Enum` class with any mix-in or data-type. +For example: + ```python class StrEnum(str, Enum): pass ``` -[enum-docs]: https://docs.python.org/3/library/enum.html -[enum-auto-docs]: https://docs.python.org/3/library/enum.html#using-auto -[enum-functional-api]: https://docs.python.org/3/library/enum.html#functional-api -[restricted-enums]: https://docs.python.org/3/library/enum.html#restricted-enum-subclassing +Subclassing `Enum` is only allowed if the `enum` does **not** define any members. +See the [`enum` how-to][enum-docs] and the [`enum` cookbook][cookbook] for more details and explanations. + +[class-decorator]: https://docs.python.org/3/reference/compound_stmts.html#class-definitions +[cookbook]: https://docs.python.org/3/howto/enum.html#enum-cookbook +[enum-auto-docs]: https://docs.python.org/3/library/enum.html#enum.auto +[enum-docs]: https://docs.python.org/3/howto/enum.html#enum-basic-tutorial +[enum-functional-example]: https://docs.python.org/3/library/enum.html [identity-keyword]: https://www.w3schools.com/python/ref_keyword_is.asp +[restricted-enums]: https://docs.python.org/3/howto/enum.html#restricted-enum-subclassing +[enum-unique-decorator]: https://docs.python.org/3/library/enum.html#enum.unique diff --git a/concepts/enums/introduction.md b/concepts/enums/introduction.md index ea9c9000e07..5d80bf50f90 100644 --- a/concepts/enums/introduction.md +++ b/concepts/enums/introduction.md @@ -1,14 +1,19 @@ # Introduction -In Python, [an enum](https://docs.python.org/3/library/enum.html) is a set of names that are bound to unique `literal`, or `constant` values. Enums are defined by inheriting an `Enum` class. Built-in enum types are available in the module `enum` and the class `Enum` can be imported using `from enum import Enum`. +In Python, [an `enum`](https://docs.python.org/3/library/enum.html) is a set of names that are bound to unique `literal`, or `constant` values. +Enums are defined by inheriting from or subclassing an `Enum` class. +Built-in `enum` types are available in the module `enum` and the class `Enum` can be imported using `from enum import Enum`. + ```python +from enum import Enum + class Color(Enum): RED = 1 GREEN = 2 ``` -Note that the values of the enum members can be any data types such as str, tuple, float, etc. +Note that the values of the `enum` members can be any data types such as `str`, `tuple`, `float`, etc. ```python class Color(Enum): @@ -16,7 +21,7 @@ class Color(Enum): GREEN = 'green' ``` -When assigning the same value to two members in an enum, the latter assigned member will be an alias to the formed one. It is not allowed to use the same name for two members of an enum. +When assigning the same value to two members in an `enum`, the latter assigned member will be an alias to the former one. It is not allowed to use the same name for two different members of an `enum`. ```python class Color(Enum): @@ -31,7 +36,7 @@ Color.ALIAS_OF_RED.value #=> 1 ``` -Iterating through the members of the enum can be done with the standard `for member in` syntax: +Iterating through the members of the `enum` can be done with the standard `for member in` syntax: ```python for member in Color: @@ -40,7 +45,7 @@ for member in Color: #=> (GREEN, 2) ``` -Enum members can be compared using [`is` (_identity operator_)](https://www.w3schools.com/python/ref_keyword_is.asp) or `is not`. The `==` or `!=` (_equality_operators_) work likewise. +`Enum` members can be compared using [`is` (_identity operator_)](https://www.w3schools.com/python/ref_keyword_is.asp) or `is not`. The `==` or `!=` (_equality operators_) work likewise: ```python a = Color.RED @@ -52,7 +57,7 @@ a == Color.RED #=> True ``` -To access an enum member for a given value, `EnumName(value)` can be used: +To access an `enum` member for a given value, `()` can be used: ```python g = Color(2) diff --git a/concepts/fractions/about.md b/concepts/fractions/about.md index d41124c39c4..568d038f829 100644 --- a/concepts/fractions/about.md +++ b/concepts/fractions/about.md @@ -1,6 +1,6 @@ # About -The [`Fractions`][fractions] module allows us to create and work with [`rational numbers`][rational]: fractions with an integer numerator divided by an integer denominator. +The [`fractions`][fractions] module allows us to create and work with [`rational numbers`][rational]: fractions with an integer numerator divided by an integer denominator. For example, we can store `2/3` as an exact fraction instead of the approximate `float` value `0.6666...` @@ -8,10 +8,10 @@ For example, we can store `2/3` as an exact fraction instead of the approximate Unlike `int`, `float`, and `complex` numbers, fractions do not have a literal form. -However, the fractions constructor is quite flexible. +However, the fraction constructor is quite flexible. -Most obviously, it can take take two integers. -Common factors are automatically removed, converting the fraction to its "lowest form": the smallest integers that accurately represent the fraction. +Most obviously, it can take two integers. +Common factors are automatically removed, converting the fraction to its "lowest form" (_the smallest integers that accurately represent the fraction_): ```python diff --git a/concepts/fractions/introduction.md b/concepts/fractions/introduction.md index 437ccbbeb07..56c19898173 100644 --- a/concepts/fractions/introduction.md +++ b/concepts/fractions/introduction.md @@ -1,13 +1,13 @@ # Introduction -The [`Fractions`][fractions] module allows us to create and work with [`rational numbers`][rational]: fractions with an integer numerator divided by an integer denominator. +The [`fractions`][fractions] module allows us to create and work with [`rational numbers`][rational]: fractions with an integer numerator divided by an integer denominator. For example, we can store `2/3` as an exact fraction instead of the approximate `float` value `0.6666...`. Unlike `int`, `float`, and `complex` numbers, fractions do not have a literal form. -However, the fractions constructor is quite flexible. +However, the fraction constructor is quite flexible. -Most obviously, it can take take two integers as arguments. -Common factors are automatically removed, converting the fraction to its "lowest form": the smallest integers that accurately represent the fraction: +Most obviously, it can take two integers as arguments. +Common factors are automatically removed, converting the fraction to its "lowest form" (_the smallest integers that accurately represent the fraction_): ```python >>> from fractions import Fraction From 810f97ff56a0014dfdd71d9270ac852452b52e22 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Wed, 20 May 2026 17:52:26 -0700 Subject: [PATCH 2/3] Stray backticks missing. --- concepts/enums/about.md | 2 +- concepts/enums/introduction.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/concepts/enums/about.md b/concepts/enums/about.md index f227372205e..dacd7bfd755 100644 --- a/concepts/enums/about.md +++ b/concepts/enums/about.md @@ -1,7 +1,7 @@ # About In Python, [an enum][enum-docs] is a set of unique names that are bound unique, **constant** values. -Enums are defined by inheriting an `Enum` class. +`Enums` are defined by inheriting an `Enum` class. Built-in enum types are available in the module `enum` and the class `Enum` can be imported using `from enum import Enum`. diff --git a/concepts/enums/introduction.md b/concepts/enums/introduction.md index 5d80bf50f90..01521b7c079 100644 --- a/concepts/enums/introduction.md +++ b/concepts/enums/introduction.md @@ -1,7 +1,7 @@ # Introduction In Python, [an `enum`](https://docs.python.org/3/library/enum.html) is a set of names that are bound to unique `literal`, or `constant` values. -Enums are defined by inheriting from or subclassing an `Enum` class. +`Enums` are defined by inheriting from or subclassing an `Enum` class. Built-in `enum` types are available in the module `enum` and the class `Enum` can be imported using `from enum import Enum`. From 955f823bfa4c613eb08bf4ecb8bf3a05cda21605 Mon Sep 17 00:00:00 2001 From: BethanyG Date: Wed, 20 May 2026 18:30:14 -0700 Subject: [PATCH 3/3] Applied fixes from code review. --- concepts/enums/introduction.md | 7 +++++-- concepts/fractions/about.md | 2 +- concepts/fractions/introduction.md | 2 +- 3 files changed, 7 insertions(+), 4 deletions(-) diff --git a/concepts/enums/introduction.md b/concepts/enums/introduction.md index 01521b7c079..bf4e8b9d043 100644 --- a/concepts/enums/introduction.md +++ b/concepts/enums/introduction.md @@ -1,6 +1,6 @@ # Introduction -In Python, [an `enum`](https://docs.python.org/3/library/enum.html) is a set of names that are bound to unique `literal`, or `constant` values. +In Python, [an `enum`][enum-docs] is a set of names that are bound to unique `literal`, or `constant` values. `Enums` are defined by inheriting from or subclassing an `Enum` class. Built-in `enum` types are available in the module `enum` and the class `Enum` can be imported using `from enum import Enum`. @@ -45,7 +45,7 @@ for member in Color: #=> (GREEN, 2) ``` -`Enum` members can be compared using [`is` (_identity operator_)](https://www.w3schools.com/python/ref_keyword_is.asp) or `is not`. The `==` or `!=` (_equality operators_) work likewise: +`Enum` members can be compared using [`is` (_identity operator_)][identity-keyword] or `is not`. The `==` or `!=` (_equality operators_) work likewise: ```python a = Color.RED @@ -68,3 +68,6 @@ g is Color.GREEN g #=> ``` + +[enum-docs]: https://docs.python.org/3/library/enum.html +[identity-keyword]: https://www.w3schools.com/python/ref_keyword_is.asp diff --git a/concepts/fractions/about.md b/concepts/fractions/about.md index 568d038f829..e582c53141a 100644 --- a/concepts/fractions/about.md +++ b/concepts/fractions/about.md @@ -29,7 +29,7 @@ Fraction(2, 3) # automatically simplified True ``` -The fractions constructor can also parse a string representation: +The fraction constructor can also parse a string representation: ```python diff --git a/concepts/fractions/introduction.md b/concepts/fractions/introduction.md index 56c19898173..156aa3ff280 100644 --- a/concepts/fractions/introduction.md +++ b/concepts/fractions/introduction.md @@ -24,7 +24,7 @@ Fraction(2, 3) # automatically simplified True ``` -The fractions constructor can also parse a string representation: +The fraction constructor can also parse a string representation: ```python >>> f3 = Fraction('2/3')