enums. iterate on the log-level exercise (exercism#2811)

* enums. iterate on the log-level exercise

* chnage hints and other files

* minor changes

* minor fixes

* straightforward changes

* [CI] Format code

Co-authored-by: BethanyG <[email protected]>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 3 people

concepts/enums/about.md

@@ -0,0 +1,111 @@
+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
+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.
+
+```python
+class Color(Enum):
+    RED = 'red'
+    GREEN = 'green'
+```
+
+Enums can also be created via the following [functional API][enum-functional-api].
+
+```python
+Animal = Enum('Animal', 'ANT BEE CAT DOG')
+list(Animal)
+#=> [<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]
+
+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.
+
+```python
+class Color(Enum):
+    RED = 1
+    GREEN = 2
+    ALIAS_OF_RED = 1
+
+Color.ALIAS_OF_RED
+#=> <Color.RED: 1>
+```
+
+Iterating through the members of the enum can be done with the standard `for member in` syntax:
+
+```python
+for member in Color:
+    print((member.name, member.value))
+#=> (RED, 1)
+#=> (GREEN, 2)
+
+# __members__.items() helps you to loop through alias as well
+for member in Color.__members__.items():
+    print(member)
+#=>('RED', <Color.RED: 1>)
+#=>('GREEN', <Color.GREEN: 2>)
+#=>('ALIAS_OF_RED', <Color.RED: 1>)
+```
+
+Enum members can be compared using [`is` (_identity operator_)][identity-keyword] or `is not`. The `==` or `!=` (_equality operators_) work likewise.
+
+```python
+a = Color.RED
+
+a is Color.RED
+#=> True
+
+a == Color.RED
+#=> True
+```
+
+To assign integer values, the [`auto()` function][enum-auto-docs] starts with `1` and automatically sets subsequent values.
+
+```python
+class Shape(Enum):
+    CIRCLE = auto()
+    SQUARE = auto()
+    OVAL = auto()
+```
+
+To disallow aliasing (_preventing duplicate values with different names_), the `@unique` decorator may be used.
+
+```python
+@unique
+class Shape(Enum):
+    CIRCLE = 1
+    SQUARE = 2
+    TRIANGLE = 1
+#=> ValueError: duplicate values found in <enum 'Shape'>: TRIANGLE -> CIRCLE
+```
+
+To access an enum member for a given value, this notation can be used: `EnumName(value)`.
+
+```python
+g = Color(2)
+
+g is Color.GREEN
+#=> True
+
+g
+#=> <Color.GREEN: 2>
+```
+
+A custom [restricted `Enum`][restricted-enums] can be written by subclassing `Enum` 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
+[identity-keyword]: https://www.w3schools.com/python/ref_keyword_is.asp

concepts/enums/links.json

@@ -0,0 +1,22 @@
+[
+  {
+    "url": "https://docs.python.org/3/library/enum.html",
+    "description": "enum documentation"
+  },
+  {
+    "url": "https://www.w3schools.com/python/ref_keyword_is.asp",
+    "description": "identity keyword"
+  },
+  {
+    "url": "https://docs.python.org/3/library/enum.html#using-auto",
+    "description": "enum auto documentation"
+  },
+  {
+    "url": "https://docs.python.org/3/library/enum.html#functional-api",
+    "description": "enum functional api"
+  },
+  {
+    "url": "https://docs.python.org/3/library/enum.html#restricted-enum-subclassing",
+    "description": "restricted enum"
+  }
+]

exercises/concept/log-levels/.docs/after.md

@@ -4,21 +4,28 @@
 
 ## 1. Parse log level
 
-- You need to use string splits to split the log message to multiple parts.
-- Once you have the required part of the string split you can use LogLevel(`string`) to return
+- Use [`str.split`](https://www.w3schools.com/python/ref_string_split.asp) to extract the log level from the message.
+- With the extracted part of the string, access and return the enum member using `LogLevel(string)`.
 
 ## 2. Support unknown log level
 
-- You need to first check if the value is in the LogLevel enum before calling LogLevel(`string`) and return.
+- Create a new Unknown log level member in the existing enum.
+- Check if the extracted part of the string is a value of the enum `LogLevel`.
+- If the value does not match any of the enum member values, then return the Unknown member of `LogLevel`.
 
 ## 3. Convert log line to short format
 
-- You need to do an if else with all the members of the LogLevel and return the String along with the int value as per the given format. ( You need to use a `==` operator )
+- Find the code (an integer) of the log level based on the log level, multiple solutions are possible: if statements, another enum or any other solution.
+- Use string formatting to return a properly formatted code level and message.
 
 ## 4. Create an Alias
 
-- You just have to return the newly created alias value to the function output.
+- Create the new alias member named Warn in the existing enum.
+- Return the newly created member.
 
 ## 5. All Member Names and Values
 
-- You need to iterate over all the members in the enum and return a tuple containing (member.name, member.value) in a list.
+- Iterate on all the members of the enum and return a list of tuple.
+- The tuple can be constructed with `(item1, item2)`.
+- The name and value of the enum can be accessed with `member.name` and `member.value`.
+- Return the list containing all the tuples.

exercises/concept/log-levels/.docs/hints.md

@@ -1,32 +1,22 @@
-In this exercise you'll be processing log-lines.
+In this exercise, you'll be processing log messages with six severity levels.
 
 Each log line is a string formatted as follows: `"[<LVL>]: <MESSAGE>"`.
 
 These are the different log levels:
 
-- `TRC` (trace)
-- `DBG` (debug)
-- `INF` (info)
-- `WRN` (warning)
-- `ERR` (error)
-- `FTL` (fatal)
-
-You have three tasks.
+| LEVEL     | LVL   |
+| --------- | ----- |
+| `Trace`   | `TRC` |
+| `Debug`   | `DBG` |
+| `Info`    | `INF` |
+| `Warning` | `WRN` |
+| `Error`   | `ERR` |
+| `Fatal`   | `FTL` |
 
 ## 1. Parse log level
 
-Define a `LogLevel` enum that has six elements corresponding to the above log levels.
-
-- `Trace`
-- `Debug`
-- `Info`
-- `Warning`
-- `Error`
-- `Fatal`
-
-Define the `parse_log_level` function which will take the 1 parameter, the log message. Return the Type of Log Level the log message belongs to.
-
-Note: The `LogLevel` enum has to be defined on top of the file (outside the function).
+Define a `LogLevel` enum that has six elements corresponding to the log levels defined above.
+Next, define the `parse_log_level` function which takes the log message as parameter and returns the enum member of its level.
 
 ```python
 parse_log_level("[INF]: File deleted")
@@ -35,64 +25,61 @@ parse_log_level("[INF]: File deleted")
 
 ## 2. Support unknown log level
 
-Unfortunately, occasionally some log lines have an unknown log level. To gracefully handle these log lines, add an `Unknown` element to the `LogLevel` enum which should be returned when parsing an unknown log level:
+Unfortunately, some log messages occasionally appear with an _unknown_ severity. To gracefully handle these 'mysterious' log messages in the function `parse_log_level`, add an `Unknown` member to the `LogLevel` enum which is returned when parsing an unknown log level:
 
 ```python
 parse_log_level("[XYZ]: Overly specific, out of context message")
 #=> LogLevel.Unknown
 ```
 
-## 3. Convert log line to short format
+## 3. Convert a log message to the short format
 
-The log level of a log line is quite verbose. To reduce the disk space needed to store the log lines, a short format is developed: `"[<ENCODED_LEVEL>]:<MESSAGE>"`.
+The log level of a log line is quite verbose. To reduce the disk space needed to store the log messages, a short format is defined: `"[<CODE_LEVEL>]:<MESSAGE>"`.
 
-The encoded log level is simple mapping of a log level to a number:
+The log level codes follow a straightforward mapping:
 
-- `Trace` - `0`
-- `Debug` - `1`
-- `Info` - `4`
-- `Warning` - `5`
-- `Error` - `6`
-- `Fatal` - `7`
-- `Unknown` - `42`
+| LEVEL     | CODE |
+| --------- | ---- |
+| `Trace`   | `0`  |
+| `Debug`   | `1`  |
+| `Info`    | `4`  |
+| `Warning` | `5`  |
+| `Error`   | `6`  |
+| `Fatal`   | `7`  |
+| `Unknown` | `42` |
 
-Define the `convert_to_short_log()` which takes 2 parameters.
+Define the `convert_to_short_log()` function, which takes two parameters:
 
-1. Log level - The Log level of the log sent. ex: LogLevel.Error
-2. Log Message
+1. Log level - The Log level of the log sent. ex: `LogLevel.Error`.
+2. Log Message - The message of type `str`.
 
 ```python
 convert_to_short_log(LogLevel.Error, "Stack overflow")
 # => "6:Stack overflow"
 ```
 
-## 4. Create an Alais
+## 4. Create an Alias
 
-It looks like the user has created logs for `LogLevel.Warn` instead of `LogLevel.Warning`. Create an `alias` for `LogLevel.Warning` and return the alias name. This can be done on the same enum class you have defined at the top of the file.
+It looks like the user has created logs for `LogLevel.Warn` instead of `LogLevel.Warning`. Create an `alias` for `LogLevel.Warning` and return the new alias member in the function `get_warn_alias`.
 
-Note: Both the LogLevels should point to same value. ie: LogLevel.Warning = "WRN" & LogLevel.Warn = "WRN"
+This can be done on the same enum class `LogLevel` already defined at the top of the file. Both the LogLevels should point to same value: `"WRN"`.
 
 ```python
-return_alias()
+get_warn_alias()
 #=> LogLevel.Warn
-return_alias() == LogLevel.Warning
+
+get_warn_alias() == LogLevel.Warning
 #=> True
 ```
 
 ## 5. All Member Names and Values
 
-Define the function `return_members()` that will take 1 parameter.
-
-1. This parameter will take a randomly created enum.
+Define the function `get_members()`.
 
-You should return the (name, value) in tuple format of all the members in a list.
+This function should return a list of tuples `(name, value)` containing all the members of the enum `LogLevel`.
 
 ```python
-
-class Color(enum.Enum):
-    RED = 'red'
-    GREEN = 'green'
-
-return_members(Color)
-#=> [('RED', 'red'), ('GREEN', 'green')]
+get_members()
+#=> [('Trace', 'TRC'), ('Debug', 'DBG'), ('Info', 'INF'), ('Warning', 'WRN'),
+# ('Error', 'ERR'), ('Fatal', 'FTL'), ('Unknown', 'UKN')]
 ```