diff --git a/concepts/enums/about.md b/concepts/enums/about.md index 27b264c22e1..dacd7bfd755 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..bf4e8b9d043 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`][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`. + ```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_)][identity-keyword] 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) @@ -63,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 d41124c39c4..e582c53141a 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 @@ -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 437ccbbeb07..156aa3ff280 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 @@ -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')