[Python] Implement new Concept Exercise: Enum

[BethanyG]

This issue describes how to implement the Enum concept exercise for the Python track.

Getting started

Please please please read the docs before starting. Posting PRs without reading these docs will be a lot more frustrating for you during the review cycle, and exhaust Exercism's maintainers' time. So, before diving into the implementation, please read up on the following documents:

• The features of v3.
• Rationale for v3.
• What are concept exercise and how they are structured?

Please also watch the following video:

• The Anatomy of a Concept Exercise.

Goal

The goal of this exercise is to teach the student how Enums (Enumerations) 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 (<, >, <=, '>=) betweenenumeration 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 to refer to

• Exercism v3 C# Enums concept exercise
• Python Docs: Enum
• Enum - Mouse vs. Python
• Why you should use more enums in Python - Florian Dahlitz
• Python Docs: How are Enums Different?
• Python Docs: The Enum Functional API
• Stack Overflow: Python enum, when and where to use?
• PEP435: Adding an Enum Type to the Python Standard Library
• Using Enums and Django model Choices - Ben Cleary

Hints

Should be focused on basic definition & use, and refer to one or more of the Python related links above (or equivalent/analogous links).

After

Some links and extended discussion of what problems an enumeration type is trying to solve in python programming might be useful to the student here. In particular, the rejected PEP354, and the subsequent accepted PEP435, as well as other discussion and links from the resources section.

It might also be useful to point the student toward all the rich customization options available for enum, such as the "interesting examples" section of the docs.

Finally, some discussion, links and usage around the "out of scope" cases above could be great to encourage the student to explore enums even further.

Representer

TBD

Analyzer

TBD

Implementing

Tests should be written using unittest.TestCase (we try to avoid using PyTest specific features), & the test file shoul dbe named enum_test.py.

Help

If you have any questions while implementing the exercise, please post the questions as comments in this issue, and/or reach out on the #python-maintainers channel in the exercism Slack team.

[BethanyG]

@mohanrajanr - all yours! LMK if you have questions or issues.

[BethanyG]

@cmccandless - when you get a chance, if you could give this a quick "sniff test" as a concept/issue & LMK if we need to edit it that would be awesome. Thank you.

[mohanrajanr]

Link to the PR Here: https://github.com/exercism/v3/pull/2312

[cmccandless]

@cmccandless - when you get a chance, if you could give this a quick "sniff test" as a concept/issue & LMK if we need to edit it that would be awesome. Thank you.

My thoughts:

• Learning objectives section feels like it's too much for a single exercise. Maybe move Functional API and aliases/@unique to "Out of scope"?
• Perhaps a mention in after.md (or whatever document is replacing it) about how enumerate is not the same thing as Enum; someone new to Python might learn Enum, then see enumerate and get confused.

[BethanyG]

Excellent feedback, @cmccandless . Thank you. I went ahead and merged the PR, but will be filing some improvement issues as I go back through our existing exercises and fill in concept docs, re-title, etc. etc. Makes sense to move @unique out, as well as aliases. I think the Functional API, being an alternative and shorter constructor should stay.

And we definitely want the Enum vs enumerate() distinction in the after.md or approaches.md .

[BethanyG]

PR #2312 Has been merged. Closing this issue.