Add deprecation annotation to Enum

[s3bw]

Add deprecation annotations to Enums

In some cases we wish to deprecate members of an enum. This will allow users of a library or of an enum class to receive warning that an enum member will be deprecated ahead of time.

We can achieve deprecation of an enum by adding it to ignore, however this doesn't allow us to warn users ahead of time.

I've introduced a method for user's of python Enum to annotate the enum's members:

from enum import Enum

class Colour(Enum):
    _ignore_ = ["red"]
    _deprecated_ = ["yellow"]

    red = 1
    blue = 2
    green = 3
    yellow = 4

In the above example, red will raise an ValueError due to being ignored. While yellow will raise a warning to the user of yellow. As shown below:

$ ./python.exe concept.py
/cpython/concept.py:15: DeprecationWarning: 'yellow' is a deprecated Colour.
  Colour(4)
/cpython/concept.py:16: DeprecationWarning: 'yellow' is a deprecated Colour.
  Colour["yellow"]
example.py:13: DeprecationWarning: 'yellow' is a deprecated Colour.
  Colour.yellow

Another example:

from enum import Enum

class NotificationType(Enum):
    _deprecated_ = ["offers"]

    marketing = 1
    budgeting = 2
    # Offer has been deprecated in favour of more granular
    # notification types: 'awards' and 'promotions'
    offers = 3
    milestones = 4
    awards = 5
    promotions = 6

Inspired from Java, which allows the use of an @deprecated annotation:

enum Status {
    OK,
    ERROR,

    @Deprecated
    PROBLEM
}

[github-actions]

This PR is stale because it has been open for 30 days with no activity.