Merge pull request #10 from irgeek/comparable

* Add a Comparable mix-in
* Add a MACRO_CASE StrEnum
* Add RTD documentation - https://strenum.readthedocs.io/en/latest/
* Drop Python 3.5 in tests

Author: irgeek

.github/workflows/python-package.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.5, 3.6, 3.7, 3.8, 3.9]
+        python-version: [3.6, 3.7, 3.8, 3.9]
 
     steps:
       - uses: actions/checkout@v2

.readthedocs.yaml

@@ -0,0 +1,15 @@
+---
+version: 2
+sphinx:
+  configuration: docs/conf.py
+
+formats:
+  - pdf
+
+python:
+  version: 3.8
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

Makefile

@@ -29,6 +29,14 @@ upload-test: .venv/bin/twine dist
 .venv/bin/twine: .venv
 	@.venv/bin/python3 -m pip install .[test,release]
 
+.venv/bin/sphinx-build: .venv
+	@.venv/bin/python3 -m pip install .[docs]
+
 clean:
 	@rm -rf .venv/ dist/ build/ *.egg-info .tox/ .eggs/ .pytest_cache/ .coverage
 	@find -d * -name '*.pyc' -delete -o -name __pycache__ -delete
+
+SPHINX_COMMANDS := html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf latexpdfja text man texinfo info gettext changes xml pseudoxml linkcheck doctest coverage
+
+$(SPHINX_COMMANDS): .venv/bin/sphinx-build
+	@cd docs && ../.venv/bin/sphinx-build -M $@ . build

README.md

@@ -131,6 +131,11 @@ python3 -m venv .venv
 ## License
 [MIT](https://choosealicense.com/licenses/mit/)
 
+Contents
+--------
+
+* [API Reference](api_ref.md)
+
 **N.B. Starting with Python 3.10, `enum.StrEnum` is available in the standard
 library.  This implementation is _not_ a drop-in replacement for the standard
 library implementation. Sepcifically, the Python devs have decided to case fold

docs/api_ref.md

@@ -0,0 +1,20 @@
+API Reference
+=============
+
+Enum Classes
+------------
+
+```eval_rst
+.. automodule:: strenum
+    :members:
+    :show-inheritance:
+```
+
+Mix-in Classes
+--------------
+
+```eval_rst
+.. automodule:: strenum.mixins
+    :members:
+    :show-inheritance:
+```

docs/conf.py

@@ -0,0 +1,76 @@
+# Configuration file for the Sphinx documentation builder.
+# pylint: disable=invalid-name,redefined-builtin,wrong-import-position
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+import recommonmark
+from recommonmark.transform import AutoStructify
+
+sys.path.insert(0, os.path.abspath(".."))
+
+
+import strenum
+
+# -- Project information -----------------------------------------------------
+
+project = "StrEnum"
+copyright = "2021, James Sinclair"
+author = "James Sinclair"
+
+# The full version, including alpha/beta/rc tags
+release = strenum.__version__
+github_doc_root = "https://github.com/irgeek/strenum/tree/master/docs/"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    # "sphinx.ext.autosectionlabel",
+    "sphinx.ext.autodoc",
+    # "sphinx.ext.viewcode",
+    # "sphinx.ext.autosummary",
+    "recommonmark",
+]
+
+source_suffix = [".rst", ".md"]
+master_doc = "index"
+templates_path = []
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = []
+
+exclude_patterns = [".venv"]
+
+pygments_style = "sphinx"
+
+autodoc_default_flags = ["members"]
+autosummary_generate = True
+
+
+def setup(app):
+    app.add_config_value(
+        "recommonmark_config",
+        {
+            #'url_resolver': lambda url: github_doc_root + url,
+            "auto_toc_tree_section": "Contents",
+            "enable_math": False,
+            "enable_inline_math": False,
+            "enable_eval_rst": True,
+        },
+        True,
+    )
+    app.add_transform(AutoStructify)

docs/index.md

@@ -0,0 +1 @@
+../README.md

pytest.ini

@@ -1,3 +1,3 @@
 [pytest]
-addopts = --cov=strenum --cov-report term-missing --black --pylint --ignore=versioneer.py --ignore=strenum/_version.py
+addopts = --cov=strenum --cov-report term-missing --black --pylint --ignore=versioneer.py --ignore=strenum/_version.py --ignore=docs/
 filterwarnings = ignore::DeprecationWarning

setup.py

@@ -24,14 +24,17 @@
             "pytest-pylint",
             "pylint",
         ],
+        "docs": [
+            "sphinx",
+            "sphinx_rtd_theme",
+            "recommonmark",
+        ],
         "release": ["twine"],
     },
     setup_requires=["pytest-runner"],
-    install_requires=["aenum;python_version<'3.6'"],
     classifiers=[
         "Development Status :: 5 - Production/Stable",
         "Programming Language :: Python :: 3 :: Only",
-        "Programming Language :: Python :: 3.5",
         "Programming Language :: Python :: 3.6",
         "Programming Language :: Python :: 3.7",
         "Programming Language :: Python :: 3.8",

strenum/__init__.py

@@ -1,8 +1,4 @@
-try:
-    import aenum as enum
-except ImportError:
-    import enum
-
+import enum
 from ._version import get_versions
 from ._name_mangler import _NameMangler
 
@@ -21,11 +17,26 @@
 # `self` arguments.
 # pylint: disable=no-self-argument
 
+"""
+StrEnum contains a collection of subclasses of Python's `enum.Enum` that
+inherit from `str` to complement `enum.IntEnum` in the standard library.
+"""
+
 
 class StrEnum(str, enum.Enum):
     """
-    StrEnum is a Python `enum.Enum` that inherits from `str` to complement
-    `enum.IntEnum` in the standard library.
+    StrEnum is a Python `enum.Enum` that inherits from `str`.
+
+    Example usage::
+
+        class Example(StrEnum):
+            UPPER_CASE = auto()
+            lower_case = auto()
+            MixedCase = auto()
+
+        assert Example.UPPER_CASE == "UPPER_CASE"
+        assert Example.lower_case == "lower_case"
+        assert Example.MixedCase == "MixedCase"
     """
 
     def __new__(cls, value, *args, **kwargs):
@@ -46,8 +57,19 @@ def _generate_next_value_(name, *_):
 
 class LowercaseStrEnum(StrEnum):
     """
-    A subclass of `StrEnum` that the folds the member name to lowercase for the
-    `auto()` value.
+    A `StrEnum` that the folds values to lowercase.
+
+    Example usage::
+
+        class Example(LowercaseStrEnum):
+            UPPER_CASE = auto()
+            lower_case = auto()
+            MixedCase = auto()
+
+        assert Example.UPPER_CASE == "upper_case"
+        assert Example.lower_case == "lower_case"
+        assert Example.MixedCase == "mixedcase"
+
     """
 
     def _generate_next_value_(name, *_):
@@ -56,8 +78,18 @@ def _generate_next_value_(name, *_):
 
 class UppercaseStrEnum(StrEnum):
     """
-    A subclass of `StrEnum` that the folds the member name to uppercase for the
-    `auto()` value.
+    A `StrEnum` that the folds values to UPPERCASE.
+
+    Example usage::
+
+        class Example(UppercaseStrEnum):
+            UPPER_CASE = auto()
+            lower_case = auto()
+            MixedCase = auto()
+
+        assert Example.UPPER_CASE == "UPPER_CASE"
+        assert Example.lower_case == "LOWER_CASE"
+        assert Example.MixedCase == "MIXEDCASE"
     """
 
     def _generate_next_value_(name, *_):
@@ -66,8 +98,18 @@ def _generate_next_value_(name, *_):
 
 class CamelCaseStrEnum(StrEnum):
     """
-    A subclass of `StrEnum` that the converts the member name to camelCase for the
-    `auto()` value.
+    A `StrEnum` that the converts values to camelCase.
+
+    Example usage::
+
+        class Example(CamelCaseStrEnum):
+            UPPER_CASE = auto()
+            lower_case = auto()
+            MixedCase = auto()
+
+        assert Example.UPPER_CASE == "upperCase"
+        assert Example.lower_case == "lowerCase"
+        assert Example.MixedCase == "mixedCase"
     """
 
     def _generate_next_value_(name, *_):
@@ -76,8 +118,18 @@ def _generate_next_value_(name, *_):
 
 class PascalCaseStrEnum(StrEnum):
     """
-    A subclass of `StrEnum` that the converts the member name to PascalCase for the
-    `auto()` value.
+    A `StrEnum` that the converts values to PascalCase.
+
+    Example usage::
+
+        class Example(PascalCaseStrEnum):
+            UPPER_CASE = auto()
+            lower_case = auto()
+            MixedCase = auto()
+
+        assert Example.UPPER_CASE == "UpperCase"
+        assert Example.lower_case == "LowerCase"
+        assert Example.MixedCase == "MixedCase"
     """
 
     def _generate_next_value_(name, *_):
@@ -86,8 +138,18 @@ def _generate_next_value_(name, *_):
 
 class KebabCaseStrEnum(StrEnum):
     """
-    A subclass of `StrEnum` that the converts the member name to kebab-case for the
-    `auto()` value.
+    A `StrEnum` that the converts values to kebab-case.
+
+    Example usage::
+
+        class Example(KebabCaseStrEnum):
+            UPPER_CASE = auto()
+            lower_case = auto()
+            MixedCase = auto()
+
+        assert Example.UPPER_CASE == "upper-case"
+        assert Example.lower_case == "lower-case"
+        assert Example.MixedCase == "mixed-case"
     """
 
     def _generate_next_value_(name, *_):
@@ -96,9 +158,39 @@ def _generate_next_value_(name, *_):
 
 class SnakeCaseStrEnum(StrEnum):
     """
-    A subclass of `StrEnum` that the converts the member name to snake-case for the
-    `auto()` value.
+    A `StrEnum` that the converts values to snake_case.
+
+    Example usage::
+
+        class Example(SnakeCaseStrEnum):
+            UPPER_CASE = auto()
+            lower_case = auto()
+            MixedCase = auto()
+
+        assert Example.UPPER_CASE == "upper_case"
+        assert Example.lower_case == "lower_case"
+        assert Example.MixedCase == "mixed_case"
     """
 
     def _generate_next_value_(name, *_):
         return _name_mangler.snake(name)
+
+
+class MacroCaseStrEnum(StrEnum):
+    """
+    A `StrEnum` that the converts values to MACRO_CASE.
+
+    Example usage::
+
+        class Example(MacroCaseStrEnum):
+            UPPER_CASE = auto()
+            lower_case = auto()
+            MixedCase = auto()
+
+        assert Example.UPPER_CASE == "UPPER_CASE"
+        assert Example.lower_case == "LOWER_CASE"
+        assert Example.MixedCase == "MIXED_CASE"
+    """
+
+    def _generate_next_value_(name, *_):
+        return _name_mangler.macro(name)