Python Concept Exercise enums (exercism#2312)

Pre concept exercise re-format.

Author: mohanrajanr

exercises/concept/enums/.docs/after.md

@@ -0,0 +1,91 @@
+In Python, an enum is a set of names that are bound to unique `literal`, or `constant` values. Enums are defined the way classes are defined in python.
+
+```python
+class Color(enum.Enum):
+    RED = 1
+    GREEN = 2
+```
+
+Note that the values of the enum members can be even not int types such as str, tuple, float etc.
+
+```python
+class Color(enum.Enum):
+    RED = 'red'
+    GREEN = 'green'
+```
+
+Enums can also be created via Functional API.
+
+```python
+Animal = Enum('Animal', 'ANT BEE CAT DOG')
+list(Animal)
+#=> [<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]
+```
+
+When you assign the same value to 2 members in an enum, the latter assigned member will be an alais to the formed one.
+
+```python
+class Color(enum.Enum):
+    RED = 1
+    GREEN = 2
+    ALAIS_OF_RED = 1
+Color.ALAIS_OF_RED
+#=> Color.RED
+```
+
+You can iterate through all the members of the enum by 2 ways.
+
+```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>)
+#=>('ALAIS_OF_RED', <Color.RED: 1>)
+```
+
+You can check and compare enum members by using the (identity)`is` or `is not` operators. We can also use the `==` or `!=` operator.
+
+```python
+a = Color.RED
+
+a is Color.RED
+#=> True
+
+a == Color.RED
+#=> True
+```
+
+If you do not want to assign any value to the enum members you can use the `auto()` function
+
+```python
+class Shapes(Enum):
+    CIRCLE = auto()
+    SQUARE = auto()
+    OVAL = auto()
+```
+
+If you do not want any aliases, and want to keep the members of the enum unique. you can use the `@unique` decorator.
+
+```python
+@unique
+class Shapes(Enum):
+    CIRCLE = 1
+    SQUARE = 2
+    TRIANGLE = 1
+#=> ValueError: duplicate values found in <enum 'shapes'="">: TRIANGLE -> CIRCLE
+```
+
+There are various subclasses available for enum, such as IntEnum, etc. which allows only Int values.They can also be created by us manually.
+
+```python
+class IntEnum(int, Enum):
+    pass
+```
+
+The same can be done for StrEnum and others etc. ( with the help of Mixins.)

exercises/concept/enums/.docs/hints.md

@@ -0,0 +1,24 @@
+## General
+
+- [Python Docs: Enum](https://docs.python.org/3/library/enum.html)
+
+## 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
+
+## 2. Support unknown log level
+
+- You need to first check if the value is in the LogLevel enum before calling LogLevel(`string`) and return.
+
+## 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 )
+
+## 4. Create an Alias
+
+- You just have to return the newly created alias value to the function output.
+
+## 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.

exercises/concept/enums/.docs/instructions.md

@@ -0,0 +1,98 @@
+In this exercise you'll be processing log-lines.
+
+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.
+
+## 1. Parse log level
+
+Define a `LogLevel` enum that has six elements corresponding to the above log levels.
+
+- `Trace`
+- `Debug`
+- `Info`
+- `Warning`
+- `Error`
+- `Fatal`
+
+Defind 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).
+
+```python
+parse_log_level("[INF]: File deleted")
+#=> LogLevel.Info
+```
+
+## 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:
+
+```python
+parse_log_level("[XYZ]: Overly specific, out of context message")
+#=> LogLevel.Unknown
+```
+
+## 3. Convert log line to 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 encoded log level is simple mapping of a log level to a number:
+
+- `Trace` - `0`
+- `Debug` - `1`
+- `Info` - `4`
+- `Warning` - `5`
+- `Error` - `6`
+- `Fatal` - `7`
+- `Unknown` - `42`
+
+Define the `convert_to_short_log()` which takes 2 parameters.
+
+1. Log level - The Log level of the log sent. ex: LogLevel.Error
+2. Log Message
+
+```python
+convert_to_short_log(LogLevel.Error, "Stack overflow")
+# => "6:Stack overflow"
+```
+
+## 4. Create an Alais
+
+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.
+
+Note: Both the LogLevels should point to same value. ie: LogLevel.Warning = "WRN" & LogLevel.Warn = "WRN"
+
+```python
+return_alias()
+#=> LogLevel.Warn
+return_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.
+
+You should return the (name, value) in tuple format of all the members in a list.
+
+```python
+
+class Color(enum.Enum):
+    RED = 'red'
+    GREEN = 'green'
+
+return_members(Color)
+#=> [('RED', 'red'), ('GREEN', 'green')]
+```

exercises/concept/enums/.docs/introduction.md

@@ -0,0 +1,62 @@
+In Python, an enum is a set of names that are bound to unique `literal`, or `constant` values. Enums are defined the way classes are defined in python.
+
+```python
+class Color(enum.Enum):
+    RED = 1
+    GREEN = 2
+```
+
+Note that the values of the enum members can be even not int types such as str, tuple, float etc.
+
+```python
+class Color(enum.Enum):
+    RED = 'red'
+    GREEN = 'green'
+```
+
+Enums can also be created via Functional API.
+
+```python
+Animal = Enum('Animal', 'ANT BEE CAT DOG')
+list(Animal)
+#=> [<Animal.ANT: 1>, <Animal.BEE: 2>, <Animal.CAT: 3>, <Animal.DOG: 4>]
+```
+
+When you assign the same value to 2 members in an enum, the latter assigned member will be an alais to the formed one.
+
+```python
+class Color(enum.Enum):
+    RED = 1
+    GREEN = 2
+    ALAIS_OF_RED = 1
+Color.ALAIS_OF_RED
+#=> Color.RED
+```
+
+You can iterate through all the members of the enum by 2 ways.
+
+```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>)
+#=>('ALAIS_OF_RED', <Color.RED: 1>)
+```
+
+You can check and compare enum members by using the (identity)`is` or `is not` operators. We can also use the `==` or `!=` operator.
+
+```python
+a = Color.RED
+
+a is Color.RED
+#=> True
+
+a == Color.RED
+#=> True
+```

exercises/concept/enums/.meta/config.json

@@ -0,0 +1,9 @@
+{
+  "authors": [
+    {
+      "github_username": "mohanrajanr",
+      "exercism_username": "mohanrajanr"
+    }
+  ],
+  "forked_from": ["csharp/enums"]
+}

exercises/concept/enums/.meta/design.md

@@ -0,0 +1,70 @@
+## Goal
+
+The goal of this exercise is to teach the student how Enums ([Enumerations](https://en.wikipedia.org/wiki/Enumerated_type)) are implemented & used in Python. We will teach this through Pythons Enum class/type.
+
+## Learning objectives
+
+- What is an enumeration / enum is, and why they are needed/wanted in Python?
+- Understand the nomenclature (naming) used in reference to enums (e.g. enumeration/enum, enum members, enum member names, and enum member values)
+- Understand that enumeration members are functionally constants (and therefore should be formatted as such)
+- How Enums are different from other, more generic Python classes.
+- How to create various Enums
+  - By using the class syntax by importing & subclassing Enum.
+  - By using the Enum Functional API
+  - By defining enum members with values that include non-int types (like str, tuple, float etc.)
+  - Using the auto() function to automatically assign integer values to members when exact value types are unimportant/not needed.
+  - Creating member aliases by assigning the same value to different names (two different names can have the same value; the second name defined becomes an alias of the first)
+  - Using the class decorator @enum.unique to prevent member aliases and enforce that member values be unique.
+- How to use an enumeration and enumeration members in other functions/code
+  - Enum members are iterable in member definition order, but iteration will not include aliases.
+  - An ordered mapping of names to members can be retrieved via **members**.items()
+  - enumeration members are compared by identity, using the is/is not keywords
+  - Ordered comparison (<, >, <=, '>=) between enumeration valuesis not supported, and will throw aTypeError`.
+  - Equality/inequality comparison is defined, and == and != can be used.
+  - Comparisons between enumeration values and non-enumeration values will always return False
+
+## Out of scope
+
+- Flag enum subtype (perhaps better as an advanced exercise that includes bitwise operations)
+- IntEnum and IntFlag subtypes (since they break the semantic promises of an enum by being comparable to int)
+- mixins & multiple inheritance for the creation of Enums
+- using **new**() to customize the value of an enum member (better for an advanced/extended enum exercise)
+- omitting values
+- subclassing an "empty" pre-defined enum
+- customization of auto()
+- Pickling
+
+## Concepts
+
+- enumeration, enums
+
+## Prerequisites
+
+- `decorators, @`
+- `__init__()`
+- `classes, OOP`
+- `inheritance`
+- `iteration`
+- `iterables`
+- `dunder methods`
+- `comparisons`
+- `rich comparisons`
+- `class attributes`
+- `importing`
+- `aliasing`
+- `dicts, dict methods (specifically dict.items())`
+- `mapping types`
+- `immutable, immutability`
+- `class properties`
+
+## Resources
+
+- [Exercism v3 C# Enums concept exercise](https://github.com/exercism/v3/tree/master/languages/csharp/exercises/concept/enums)
+- [Python Docs: Enum](https://docs.python.org/3/library/enum.html)
+- [Enum - Mouse vs. Python](https://www.blog.pythonlibrary.org/2018/03/20/python-3-an-intro-to-enumerations/)
+- [Why you should use more enums in Python - Florian Dahlitz](https://florian-dahlitz.de/blog/why-you-should-use-more-enums-in-python)
+- [Python Docs: How are Enums Different?](https://docs.python.org/3/library/enum.html#how-are-enums-different)
+- [Python Docs: The Enum Functional API](https://docs.python.org/3/library/enum.html#functional-api)
+- [Stack Overflow: Python enum, when and where to use?](https://stackoverflow.com/questions/22586895/python-enum-when-and-where-to-use)
+- [PEP435: Adding an Enum Type to the Python Standard Library](https://www.python.org/dev/peps/pep-0435/)
+- [Using Enums and Django model Choices - Ben Cleary](https://medium.com/@bencleary/using-enums-as-django-model-choices-96c4cbb78b2e)