{ "cells": [ { "cell_type": "markdown", "metadata": { "pycharm": { "name": "#%% md\n" } }, "source": [ "# Enum Mate - Comprehensive Usage Guide\n", "\n", "The enum_mate library enhances Python's standard [enum](https://docs.python.org/3/library/enum.html) module with explicit APIs for validation and retrieval. It provides safer, more intuitive enum handling with comprehensive validation methods.\n", "\n", "One of the key advantages of enum_mate is its intuitive and self-explanatory API naming convention. The library uses human-friendly method and attribute names that clearly convey their purpose. This means you can leverage your IDE's auto-complete functionality to discover and use the available APIs without having to constantly refer to the documentation or memorize the exact syntax." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Import" ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "ExecuteTime": { "end_time": "2024-05-18T15:54:44.581871Z", "start_time": "2024-05-18T15:54:44.573334Z" }, "collapsed": false, "jupyter": { "outputs_hidden": false }, "pycharm": { "name": "#%%\n" } }, "outputs": [], "source": [ "from enum_mate.api import BetterIntEnum, BetterStrEnum" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## BetterIntEnum - Enhanced Integer Enums\n", "\n", "``class BetterIntEnum:`` is an more advanced version of ``class YourEnumClass(int, enum.Enum):``.\n", "\n", "### Basic Usage" ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false }, "pycharm": { "name": "#%%\n" } }, "outputs": [], "source": [ "class StatusCode(BetterIntEnum):\n", " SUCCESS = 200\n", " NOT_FOUND = 404\n", " SERVER_ERROR = 500\n", " TIMEOUT = -1" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Standard Enum Operations" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Works exactly like standard int enums\n", "StatusCode.SUCCESS == 200" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "201" ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "StatusCode.SUCCESS + 1" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "False" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "StatusCode.SUCCESS > StatusCode.NOT_FOUND" ] }, { "cell_type": "code", "execution_count": 6, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "{StatusCode.SUCCESS, StatusCode.NOT_FOUND} == {200, 404}" ] }, { "cell_type": "code", "execution_count": 7, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "StatusCode.SUCCESS\n" ] } ], "source": [ "# String representation\n", "print(StatusCode.SUCCESS) # StatusCode.SUCCESS" ] }, { "cell_type": "code", "execution_count": 8, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'SUCCESS'" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "StatusCode.SUCCESS.name" ] }, { "cell_type": "code", "execution_count": 9, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "200" ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "StatusCode.SUCCESS.value" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Enhanced API Methods\n", "\n", "#### 1. Retrieval by Name" ] }, { "cell_type": "code", "execution_count": 10, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "" ] }, "execution_count": 10, "metadata": {}, "output_type": "execute_result" } ], "source": [ "member = StatusCode.get_by_name(\"SUCCESS\")\n", "member" ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 11, "metadata": {}, "output_type": "execute_result" } ], "source": [ "member is StatusCode.SUCCESS" ] }, { "cell_type": "code", "execution_count": 12, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\"Invalid `class __main__.StatusCode` member name: 'INVALID'\"\n" ] } ], "source": [ "try:\n", " StatusCode.get_by_name(\"INVALID\")\n", "except KeyError as e:\n", " print(e)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 2. Retrieval by Value" ] }, { "cell_type": "code", "execution_count": 13, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "StatusCode.SUCCESS\n" ] } ], "source": [ "member = StatusCode.get_by_value(200)\n", "print(member)" ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 14, "metadata": {}, "output_type": "execute_result" } ], "source": [ "member is StatusCode.SUCCESS" ] }, { "cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "999 is not a valid StatusCode\n" ] } ], "source": [ "try:\n", " StatusCode.get_by_value(999)\n", "except ValueError as e:\n", " print(e)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 3. Name Validation" ] }, { "cell_type": "code", "execution_count": 16, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 16, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Check if name is valid\n", "StatusCode.is_valid_name(\"SUCCESS\")" ] }, { "cell_type": "code", "execution_count": 17, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "False" ] }, "execution_count": 17, "metadata": {}, "output_type": "execute_result" } ], "source": [ "StatusCode.is_valid_name(\"success\") # case-sensitive" ] }, { "cell_type": "code", "execution_count": 18, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "False" ] }, "execution_count": 18, "metadata": {}, "output_type": "execute_result" } ], "source": [ "StatusCode.is_valid_name(\"INVALID\")" ] }, { "cell_type": "code", "execution_count": 19, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "False" ] }, "execution_count": 19, "metadata": {}, "output_type": "execute_result" } ], "source": [ "StatusCode.is_valid_name(200) # wrong type" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 4. Value Validation" ] }, { "cell_type": "code", "execution_count": 20, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 20, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Check if value is valid\n", "StatusCode.is_valid_value(200)" ] }, { "cell_type": "code", "execution_count": 21, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 21, "metadata": {}, "output_type": "execute_result" } ], "source": [ "StatusCode.is_valid_value(-1) # negative values work" ] }, { "cell_type": "code", "execution_count": 22, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "False" ] }, "execution_count": 22, "metadata": {}, "output_type": "execute_result" } ], "source": [ "StatusCode.is_valid_value(999)" ] }, { "cell_type": "code", "execution_count": 23, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "False" ] }, "execution_count": 23, "metadata": {}, "output_type": "execute_result" } ], "source": [ "StatusCode.is_valid_value(\"200\") # wrong type" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 5. Value Validation with Exceptions" ] }, { "cell_type": "code", "execution_count": 24, "metadata": {}, "outputs": [], "source": [ "# Validate and raise exception if invalid\n", "StatusCode.ensure_is_valid_value(200) # No exception" ] }, { "cell_type": "code", "execution_count": 25, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Invalid `class __main__.StatusCode`: 999\n" ] } ], "source": [ "try:\n", " StatusCode.ensure_is_valid_value(999)\n", "except ValueError as e: # Invalid StatusCode: 999\n", " print(e)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 6. Type Conversion and Validation" ] }, { "cell_type": "code", "execution_count": 26, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "200" ] }, "execution_count": 26, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Convert to int with validation\n", "StatusCode.ensure_int(200) # 200 (int)" ] }, { "cell_type": "code", "execution_count": 27, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "200" ] }, "execution_count": 27, "metadata": {}, "output_type": "execute_result" } ], "source": [ "StatusCode.ensure_int(StatusCode.SUCCESS)" ] }, { "cell_type": "code", "execution_count": 28, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "999 is not a valid StatusCode\n" ] } ], "source": [ "# Error handling\n", "try:\n", " StatusCode.ensure_int(999)\n", "except ValueError as e:\n", " print(e)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 7. Get All Names and Values" ] }, { "cell_type": "code", "execution_count": 29, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "['SUCCESS', 'NOT_FOUND', 'SERVER_ERROR', 'TIMEOUT']" ] }, "execution_count": 29, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Get all enum names\n", "StatusCode.get_names()" ] }, { "cell_type": "code", "execution_count": 30, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "[200, 404, 500, -1]" ] }, "execution_count": 30, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Get all enum values\n", "StatusCode.get_values()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## BetterStrEnum - Enhanced String Enums\n", "\n", "### Basic Usage" ] }, { "cell_type": "code", "execution_count": 31, "metadata": {}, "outputs": [], "source": [ "class Environment(BetterStrEnum):\n", " DEVELOPMENT = \"dev\"\n", " STAGING = \"staging\"\n", " PRODUCTION = \"prod\"\n", " TEST = \"test\"" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Standard String Operations" ] }, { "cell_type": "code", "execution_count": 32, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 32, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Works exactly like standard str enums\n", "Environment.DEVELOPMENT == \"dev\"" ] }, { "cell_type": "code", "execution_count": 33, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'DEV'" ] }, "execution_count": 33, "metadata": {}, "output_type": "execute_result" } ], "source": [ "Environment.DEVELOPMENT.upper()" ] }, { "cell_type": "code", "execution_count": 34, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'Running in Environment.PRODUCTION'" ] }, "execution_count": 34, "metadata": {}, "output_type": "execute_result" } ], "source": [ "f\"Running in {Environment.PRODUCTION}\"" ] }, { "cell_type": "code", "execution_count": 35, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "{, }" ] }, "execution_count": 35, "metadata": {}, "output_type": "execute_result" } ], "source": [ "{\"dev\", \"prod\"} & {Environment.DEVELOPMENT, Environment.PRODUCTION} # {'dev', 'prod'}" ] }, { "cell_type": "code", "execution_count": 36, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'development'" ] }, "execution_count": 36, "metadata": {}, "output_type": "execute_result" } ], "source": [ "Environment.DEVELOPMENT.replace(\"v\", \"velopment\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Enhanced API Methods\n", "\n", "#### 1. Retrieval by Name" ] }, { "cell_type": "code", "execution_count": 37, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "" ] }, "execution_count": 37, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Get enum member by name\n", "member = Environment.get_by_name(\"DEVELOPMENT\")\n", "member" ] }, { "cell_type": "code", "execution_count": 38, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 38, "metadata": {}, "output_type": "execute_result" } ], "source": [ "member is Environment.DEVELOPMENT" ] }, { "cell_type": "code", "execution_count": 39, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "4429131728" ] }, "execution_count": 39, "metadata": {}, "output_type": "execute_result" } ], "source": [ "id(Environment.DEVELOPMENT)" ] }, { "cell_type": "code", "execution_count": 40, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "KeyError(\"Invalid `class __main__.Environment` member name: 'dev'\")\n" ] } ], "source": [ "# Error handling\n", "try:\n", " Environment.get_by_name(\"dev\") # Wrong - this is the value, not name\n", "except KeyError as e:\n", " print(repr(e))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 2. Retrieval by Value" ] }, { "cell_type": "code", "execution_count": 41, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "" ] }, "execution_count": 41, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Get enum member by value\n", "member = Environment.get_by_value(\"dev\")\n", "member" ] }, { "cell_type": "code", "execution_count": 42, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 42, "metadata": {}, "output_type": "execute_result" } ], "source": [ "member is Environment.DEVELOPMENT" ] }, { "cell_type": "code", "execution_count": 43, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "ValueError(\"'DEVELOPMENT' is not a valid Environment\")\n" ] } ], "source": [ "# Error handling\n", "try:\n", " Environment.get_by_value(\"DEVELOPMENT\") # Wrong - this is the name, not value\n", "except ValueError as e:\n", " print(repr(e))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 3. Name Validation" ] }, { "cell_type": "code", "execution_count": 44, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 44, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Check if name is valid\n", "Environment.is_valid_name(\"DEVELOPMENT\")" ] }, { "cell_type": "code", "execution_count": 45, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "False" ] }, "execution_count": 45, "metadata": {}, "output_type": "execute_result" } ], "source": [ "Environment.is_valid_name(\"dev\") # this is a value, not name" ] }, { "cell_type": "code", "execution_count": 46, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "False" ] }, "execution_count": 46, "metadata": {}, "output_type": "execute_result" } ], "source": [ "Environment.is_valid_name(\"INVALID\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 4. Value Validation" ] }, { "cell_type": "code", "execution_count": 47, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "True" ] }, "execution_count": 47, "metadata": {}, "output_type": "execute_result" } ], "source": [ "Environment.is_valid_value(\"dev\")" ] }, { "cell_type": "code", "execution_count": 48, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "False" ] }, "execution_count": 48, "metadata": {}, "output_type": "execute_result" } ], "source": [ "Environment.is_valid_value(\"DEVELOPMENT\") # this is a name, not value" ] }, { "cell_type": "code", "execution_count": 49, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "False" ] }, "execution_count": 49, "metadata": {}, "output_type": "execute_result" } ], "source": [ "Environment.is_valid_value(\"invalid\")" ] }, { "cell_type": "code", "execution_count": 50, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "False" ] }, "execution_count": 50, "metadata": {}, "output_type": "execute_result" } ], "source": [ "Environment.is_valid_value(\"\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 5. Value Validation with Exceptions" ] }, { "cell_type": "code", "execution_count": 51, "metadata": {}, "outputs": [], "source": [ "# Validate and raise exception if invalid\n", "Environment.ensure_is_valid_value(\"dev\") # No exception" ] }, { "cell_type": "code", "execution_count": 52, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "ValueError(\"Invalid `class __main__.Environment`: 'invalid'\")\n" ] } ], "source": [ "try:\n", " Environment.ensure_is_valid_value(\"invalid\")\n", "except ValueError as e:\n", " print(repr(e))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 6. Type Conversion and Validation" ] }, { "cell_type": "code", "execution_count": 53, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'dev'" ] }, "execution_count": 53, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Convert to str with validation\n", "Environment.ensure_str(\"dev\")" ] }, { "cell_type": "code", "execution_count": 54, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'dev'" ] }, "execution_count": 54, "metadata": {}, "output_type": "execute_result" } ], "source": [ "Environment.ensure_str(Environment.DEVELOPMENT)" ] }, { "cell_type": "code", "execution_count": 55, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "ValueError(\"'invalid' is not a valid Environment\")\n" ] } ], "source": [ "# Error handling\n", "try:\n", " Environment.ensure_str(\"invalid\")\n", "except ValueError as e:\n", " print(repr(e))" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 7. Get All Names and Values" ] }, { "cell_type": "code", "execution_count": 56, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "['DEVELOPMENT', 'STAGING', 'PRODUCTION', 'TEST']" ] }, "execution_count": 56, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Get all enum names\n", "Environment.get_names()" ] }, { "cell_type": "code", "execution_count": 57, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "['dev', 'staging', 'prod', 'test']" ] }, "execution_count": 57, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Get all enum values\n", "Environment.get_values()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Advanced Usage Examples\n", "\n", "### Input Validation in Functions" ] }, { "cell_type": "code", "execution_count": 58, "metadata": {}, "outputs": [], "source": [ "def process_request(status_code: int):\n", " \"\"\"Process request based on status code.\"\"\"\n", " # Validate input and convert to enum\n", " code = StatusCode.ensure_int(status_code)\n", " \n", " if code == StatusCode.SUCCESS:\n", " return \"Request processed successfully\"\n", " elif code == StatusCode.NOT_FOUND:\n", " return \"Resource not found\"\n", " else:\n", " return \"Request failed\"" ] }, { "cell_type": "code", "execution_count": 59, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'Request processed successfully'" ] }, "execution_count": 59, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Usage\n", "process_request(200) # Request processed successfully" ] }, { "cell_type": "code", "execution_count": 60, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'Resource not found'" ] }, "execution_count": 60, "metadata": {}, "output_type": "execute_result" } ], "source": [ "process_request(404) # Resource not found" ] }, { "cell_type": "code", "execution_count": 61, "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "ValueError('999 is not a valid StatusCode')\n" ] } ], "source": [ "try:\n", " process_request(999)\n", "except ValueError as e:\n", " print(repr(e)) # Invalid status code: 999" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Configuration Management" ] }, { "cell_type": "code", "execution_count": 62, "metadata": {}, "outputs": [], "source": [ "def get_database_config(env_name):\n", " \"\"\"Get database configuration for environment.\"\"\"\n", " # Ensure valid environment\n", " env = Environment.ensure_str(env_name)\n", " \n", " configs = {\n", " Environment.DEVELOPMENT: \"localhost:5432\",\n", " Environment.STAGING: \"staging-db:5432\",\n", " Environment.PRODUCTION: \"prod-db:5432\",\n", " Environment.TEST: \"test-db:5432\"\n", " }\n", " \n", " return configs[env]" ] }, { "cell_type": "code", "execution_count": 63, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'localhost:5432'" ] }, "execution_count": 63, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Usage\n", "get_database_config(\"dev\")" ] }, { "cell_type": "code", "execution_count": 64, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "'prod-db:5432'" ] }, "execution_count": 64, "metadata": {}, "output_type": "execute_result" } ], "source": [ "get_database_config(\"prod\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Summary\n", "\n", "The ``enum_mate`` library provides:\n", "\n", "- **Explicit APIs** for getting enum members by name or value\n", "- **Built-in validation** methods for safe enum handling\n", "- **Type conversion** utilities with validation\n", "- **Comprehensive error handling** with clear error messages\n", "- **Full compatibility** with standard Python enum operations\n", "- **IDE-friendly** method names for better development experience\n", "\n", "Use ``BetterIntEnum`` for integer-based enums and ``BetterStrEnum`` for string-based enums to get enhanced functionality while maintaining all standard enum capabilities." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "kernelspec": { "display_name": "Python 3 (ipykernel)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.11.8" } }, "nbformat": 4, "nbformat_minor": 4 }