| Name | basicenum JSON |
| Version |
2023.1
JSON |
| download |
| home_page | |
| Summary | Simple(r) enums |
| upload_time | 2023-12-22 19:13:36 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.9 |
| license | Copyright 2022 Brett Cannon Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
enum
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# basicenum
Simple(r) enums.
## `basicenum.compat`
A (mostly) API-compatible re-implementation of
[`enum.Enum`](https://docs.python.org/3/library/enum.html#enum.Enum) from the
stdlib (plus related code).
The goal for this module was to try and re-implement as much of the API of
`enum.Enum` as possible while using modern Python features. While this does lead
to some API breakage (e.g. `type(enum.member) == type(enum)` is no longer true),
it mostly revolves around metaclass-level details. If you rely on the surface
API for `enum.Enum`, then this module should be compatible.
### API Compatibility
Using the example enum:
```python
class Colour(Enum):
RED = auto()
GREEN = auto()
BLUE = auto()
```
The compatibility with `enum.Enum` is:
| Feature | Supported? |
| ------- | ---------- |
|`repr(Colour.RED)`|✅|
|`str(Colour.RED)`|✅|
|`type(Colour.RED)`|❌ (`Member` instead)|
|`isinstance(Colour.RED, Colour)`|✅|
|`iter(Colour)`|✅|
|`hash(Colour.RED)`|✅|
|`Colour(1)`|✅|
|`Colour["RED"]`|✅|
|`Colour.RED in Colour`|✅|
|`Colour.RED.name`|✅|
|`Colour.RED.value`|✅|
|`auto()`|✅|
|`_generate_next_value_()`|✅|
|`Colour.__members__`|✅|
|`Colour.RED == Colour.RED`|✅|
|Restricted subclassing|❌|
|Pickling|✅|
|Functional API|✅ (via `create()`)|
### Type Checking
Unfortunately, type checkers hard-code their support for `enum.Enum`. That means
they do not recognize members of `basicenum.compat.Enum` as being instances of
`Member` or matching the API of members of `enum.Enum`.
Luckily, you can lie to the type checkers. You can tell them to type check as if
you're using `enum` while using `basicenum.compat` during execution.
```python
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from enum import Enum, auto
else:
from basicenum.compat import Enum, auto
```
### Benchmarking
If you install the `[benchmark]` extra, you can use
[`richbench`](https://pypi.org/project/richbench/) to see a performance
comparison between `enum` and `basicenum.compat`.
#### Results
On a MacBook Pro (Retina, 13-inch, Early 2015):
```sh
richbench --repeat 5 --times 5 --benchmark compat benchmarks/
```
| Benchmark | Min | Max | Mean | Min (+) | Max (+) | Mean (+) |
|---------------------------|---------|---------|---------|-----------------|-----------------|-----------------|
| import | 0.374 | 0.503 | 0.422 | 0.117 (3.2x) | 0.120 (4.2x) | 0.119 (3.5x) |
| creation w/ `auto()` | 0.422 | 0.429 | 0.425 | 0.075 (5.7x) | 0.077 (5.5x) | 0.076 (5.6x) |
| `_generate_next_value_()` | 0.373 | 0.383 | 0.376 | 0.077 (4.8x) | 0.078 (4.9x) | 0.078 (4.8x) |
| creation w/ constants | 0.333 | 0.351 | 0.339 | 0.060 (5.5x) | 0.066 (5.4x) | 0.063 (5.4x) |
| functional API | 0.392 | 0.397 | 0.394 | 0.070 (5.6x) | 0.074 (5.4x) | 0.072 (5.5x) |
| isinstance(..., Enum) | 0.189 | 0.191 | 0.190 | 0.279 (-1.5x) | 0.282 (-1.5x) | 0.280 (-1.5x) |
| `iter(Enum)` | 0.912 | 0.922 | 0.917 | 0.197 (4.6x) | 0.199 (4.6x) | 0.198 (4.6x) |
| `Enum(...)` | 0.297 | 0.297 | 0.297 | 0.078 (3.8x) | 0.079 (3.8x) | 0.078 (3.8x) |
| `Enum[...]` | 0.121 | 0.122 | 0.121 | 0.075 (1.6x) | 0.139 (-1.1x) | 0.093 (1.3x) |
| `... in Enum` | 0.267 | 0.375 | 0.308 | 0.162 (1.6x) | 0.164 (2.3x) | 0.163 (1.9x) |
| member access | 0.333 | 0.337 | 0.334 | 0.118 (2.8x) | 0.121 (2.8x) | 0.119 (2.8x) |
| value access | 0.735 | 0.761 | 0.744 | 0.141 (5.2x) | 0.143 (5.3x) | 0.142 (5.2x) |
| equality | 0.343 | 0.345 | 0.344 | 0.103 (3.3x) | 0.107 (3.2x) | 0.105 (3.3x) |
| repr | 0.379 | 0.386 | 0.382 | 0.236 (1.6x) | 0.238 (1.6x) | 0.237 (1.6x) |
| hashing | 0.345 | 0.355 | 0.348 | 0.245 (1.4x) | 0.250 (1.4x) | 0.247 (1.4x) |
| pickling | 0.270 | 0.272 | 0.271 | 0.270 (-1.0x) | 0.274 (-1.0x) | 0.272 (-1.0x) |
| unpickling | 0.229 | 0.232 | 0.231 | 0.230 (-1.0x) | 0.232 (-1.0x) | 0.231 (-1.0x) |
| `__members__` | 0.373 | 0.381 | 0.376 | 0.046 (8.1x) | 0.047 (8.1x) | 0.046 (8.1x) |
| `@unique` | 0.518 | 0.523 | 0.520 | 0.104 (5.0x) | 0.109 (4.8x) | 0.106 (4.9x) |
### Module Contents
#### `Enum`
The class to inherit from to create an enum.
#### `Member`
The class which all enum members are instances of.
#### `auto()`
Function for automatic, incrementing integer member values.
#### `@unique`
Guarantee that all enum members have unique values.
Raises `ValueError` if values are not all unique.
#### `create()`
A re-implementation of the functional API of `enum.Enum`.
```python
def create(
enum_name, member_names, /, *, module=None, qualname=None, type=None, start=1
): ...
```
Raw data
{
"_id": null,
"home_page": "",
"name": "basicenum",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "enum",
"author": "",
"author_email": "Brett Cannon <brett@python.org>",
"download_url": "https://files.pythonhosted.org/packages/03/1d/e40e5c09b0e582f5d7775f7118b8a56e9a050b5f335f06d9e0d996d68cce/basicenum-2023.1.tar.gz",
"platform": null,
"description": "# basicenum\n\nSimple(r) enums.\n\n## `basicenum.compat`\n\nA (mostly) API-compatible re-implementation of\n[`enum.Enum`](https://docs.python.org/3/library/enum.html#enum.Enum) from the\nstdlib (plus related code).\n\nThe goal for this module was to try and re-implement as much of the API of\n`enum.Enum` as possible while using modern Python features. While this does lead\nto some API breakage (e.g. `type(enum.member) == type(enum)` is no longer true),\nit mostly revolves around metaclass-level details. If you rely on the surface\nAPI for `enum.Enum`, then this module should be compatible.\n\n### API Compatibility\n\nUsing the example enum:\n\n```python\nclass Colour(Enum):\n RED = auto()\n GREEN = auto()\n BLUE = auto()\n```\n\nThe compatibility with `enum.Enum` is:\n\n| Feature | Supported? |\n| ------- | ---------- |\n|`repr(Colour.RED)`|\u2705|\n|`str(Colour.RED)`|\u2705|\n|`type(Colour.RED)`|\u274c (`Member` instead)|\n|`isinstance(Colour.RED, Colour)`|\u2705|\n|`iter(Colour)`|\u2705|\n|`hash(Colour.RED)`|\u2705|\n|`Colour(1)`|\u2705|\n|`Colour[\"RED\"]`|\u2705|\n|`Colour.RED in Colour`|\u2705|\n|`Colour.RED.name`|\u2705|\n|`Colour.RED.value`|\u2705|\n|`auto()`|\u2705|\n|`_generate_next_value_()`|\u2705|\n|`Colour.__members__`|\u2705|\n|`Colour.RED == Colour.RED`|\u2705|\n|Restricted subclassing|\u274c|\n|Pickling|\u2705|\n|Functional API|\u2705 (via `create()`)|\n\n### Type Checking\n\nUnfortunately, type checkers hard-code their support for `enum.Enum`. That means\nthey do not recognize members of `basicenum.compat.Enum` as being instances of\n`Member` or matching the API of members of `enum.Enum`.\n\nLuckily, you can lie to the type checkers. You can tell them to type check as if\nyou're using `enum` while using `basicenum.compat` during execution.\n\n```python\nfrom typing import TYPE_CHECKING\n\nif TYPE_CHECKING:\n from enum import Enum, auto\nelse:\n from basicenum.compat import Enum, auto\n```\n\n### Benchmarking\n\nIf you install the `[benchmark]` extra, you can use\n[`richbench`](https://pypi.org/project/richbench/) to see a performance\ncomparison between `enum` and `basicenum.compat`.\n\n#### Results\n\nOn a MacBook Pro (Retina, 13-inch, Early 2015):\n\n```sh\nrichbench --repeat 5 --times 5 --benchmark compat benchmarks/\n```\n\n| Benchmark | Min | Max | Mean | Min (+) | Max (+) | Mean (+) |\n|---------------------------|---------|---------|---------|-----------------|-----------------|-----------------|\n| import | 0.374 | 0.503 | 0.422 | 0.117 (3.2x) | 0.120 (4.2x) | 0.119 (3.5x) |\n| creation w/ `auto()` | 0.422 | 0.429 | 0.425 | 0.075 (5.7x) | 0.077 (5.5x) | 0.076 (5.6x) |\n| `_generate_next_value_()` | 0.373 | 0.383 | 0.376 | 0.077 (4.8x) | 0.078 (4.9x) | 0.078 (4.8x) |\n| creation w/ constants | 0.333 | 0.351 | 0.339 | 0.060 (5.5x) | 0.066 (5.4x) | 0.063 (5.4x) |\n| functional API | 0.392 | 0.397 | 0.394 | 0.070 (5.6x) | 0.074 (5.4x) | 0.072 (5.5x) |\n| isinstance(..., Enum) | 0.189 | 0.191 | 0.190 | 0.279 (-1.5x) | 0.282 (-1.5x) | 0.280 (-1.5x) |\n| `iter(Enum)` | 0.912 | 0.922 | 0.917 | 0.197 (4.6x) | 0.199 (4.6x) | 0.198 (4.6x) |\n| `Enum(...)` | 0.297 | 0.297 | 0.297 | 0.078 (3.8x) | 0.079 (3.8x) | 0.078 (3.8x) |\n| `Enum[...]` | 0.121 | 0.122 | 0.121 | 0.075 (1.6x) | 0.139 (-1.1x) | 0.093 (1.3x) |\n| `... in Enum` | 0.267 | 0.375 | 0.308 | 0.162 (1.6x) | 0.164 (2.3x) | 0.163 (1.9x) |\n| member access | 0.333 | 0.337 | 0.334 | 0.118 (2.8x) | 0.121 (2.8x) | 0.119 (2.8x) |\n| value access | 0.735 | 0.761 | 0.744 | 0.141 (5.2x) | 0.143 (5.3x) | 0.142 (5.2x) |\n| equality | 0.343 | 0.345 | 0.344 | 0.103 (3.3x) | 0.107 (3.2x) | 0.105 (3.3x) |\n| repr | 0.379 | 0.386 | 0.382 | 0.236 (1.6x) | 0.238 (1.6x) | 0.237 (1.6x) |\n| hashing | 0.345 | 0.355 | 0.348 | 0.245 (1.4x) | 0.250 (1.4x) | 0.247 (1.4x) |\n| pickling | 0.270 | 0.272 | 0.271 | 0.270 (-1.0x) | 0.274 (-1.0x) | 0.272 (-1.0x) |\n| unpickling | 0.229 | 0.232 | 0.231 | 0.230 (-1.0x) | 0.232 (-1.0x) | 0.231 (-1.0x) |\n| `__members__` | 0.373 | 0.381 | 0.376 | 0.046 (8.1x) | 0.047 (8.1x) | 0.046 (8.1x) |\n| `@unique` | 0.518 | 0.523 | 0.520 | 0.104 (5.0x) | 0.109 (4.8x) | 0.106 (4.9x) |\n\n### Module Contents\n\n#### `Enum`\n\nThe class to inherit from to create an enum.\n\n#### `Member`\n\nThe class which all enum members are instances of.\n\n#### `auto()`\n\nFunction for automatic, incrementing integer member values.\n\n#### `@unique`\n\nGuarantee that all enum members have unique values.\n\nRaises `ValueError` if values are not all unique.\n\n#### `create()`\n\nA re-implementation of the functional API of `enum.Enum`.\n\n```python\ndef create(\n enum_name, member_names, /, *, module=None, qualname=None, type=None, start=1\n): ...\n```\n",
"bugtrack_url": null,
"license": "Copyright 2022 Brett Cannon Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \u201cAS IS\u201d AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.",
"summary": "Simple(r) enums",
"version": "2023.1",
"project_urls": {
"Repository": "https://github.com/brettcannon/basicenum"
},
"split_keywords": [
"enum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3bb41d33a2de0ed7488c7c06703108bbe90303560b625a5ca71a5539026db73a",
"md5": "4bdbd978df41b1dbcf63c9677a817d02",
"sha256": "6c345483e4bf2c9a56a4fdf4f4713bdd47ae3f403dec265f44220c2ac54aabaa"
},
"downloads": -1,
"filename": "basicenum-2023.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4bdbd978df41b1dbcf63c9677a817d02",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 6756,
"upload_time": "2023-12-22T19:13:35",
"upload_time_iso_8601": "2023-12-22T19:13:35.279757Z",
"url": "https://files.pythonhosted.org/packages/3b/b4/1d33a2de0ed7488c7c06703108bbe90303560b625a5ca71a5539026db73a/basicenum-2023.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "031de40e5c09b0e582f5d7775f7118b8a56e9a050b5f335f06d9e0d996d68cce",
"md5": "879de74f18f826eec864bba4a99c67d9",
"sha256": "695f1e5101d89f3b74889b79b3c88c071f96352c8d5f3a1535f541961f69ae81"
},
"downloads": -1,
"filename": "basicenum-2023.1.tar.gz",
"has_sig": false,
"md5_digest": "879de74f18f826eec864bba4a99c67d9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 6792,
"upload_time": "2023-12-22T19:13:36",
"upload_time_iso_8601": "2023-12-22T19:13:36.386367Z",
"url": "https://files.pythonhosted.org/packages/03/1d/e40e5c09b0e582f5d7775f7118b8a56e9a050b5f335f06d9e0d996d68cce/basicenum-2023.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-22 19:13:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "brettcannon",
"github_project": "basicenum",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "basicenum"
}
