literalenum 0.1.1__tar.gz

literalenum-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]" 2>/dev/null || pip install -e .
+      - run: pip install pytest
+      - run: pytest
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      id-token: write
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

literalenum-0.1.1/.gitignore

@@ -0,0 +1,73 @@
+# =====================
+# Python / Build
+# =====================
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+pip-wheel-metadata/
+
+# =====================
+# Virtual Environments
+# =====================
+.venv/
+venv/
+env/
+ENV/
+
+# =====================
+# Tooling
+# =====================
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# =====================
+# Logs / Temp
+# =====================
+*.log
+*.tmp
+*.swp
+
+# =====================
+# Runtime Outputs
+# =====================
+workspace/
+*.annotated.py
+annotations.json
+report.json
+
+# =====================
+# Web Demo (if present)
+# =====================
+node_modules/
+dist-frontend/
+.build/
+.cache/
+
+# =====================
+# Secrets / Local Config
+# =====================
+.env
+.env.*
+config.local.toml
+*untracked*
+
+# =====================
+# Editors / OS
+# =====================
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+

literalenum-0.1.1/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org/>

literalenum-0.1.1/LITMUS.md

@@ -0,0 +1,58 @@
+1. **Namespace** for member access, e.g. `FieldType.A`
+    - ```python
+      x = HttpMethod.GET  # automatically seen as having type of Literal["GET"] and value of "GET"
+      ```
+    - `Literal` fails this, and I see it as `Literal`'s biggest weakness
+2. **Raw literals accepted**: `"A"` should be an acceptable input to a param typed as `t: FieldType`
+    - ```python
+      def handle(method: HttpMethod) -> None: ...
+      handle("GET") # this should be considered OK, as though HttpMethod was synonymous with Literal["GET", "POST"]
+      ```
+    - `Enum/StrEnum` fail this and I see it as their biggest weakness for SOME use cases
+    - NOTE: there are definitely times devs WANT to reject raw strings to avoid floating literals : I would not want to change `Enum/StrEnum` behavior here
+3. **Named members accepted**: `FieldType.A` should be an acceptable input to a param typed as `t: FieldType`
+    - ```python
+      def handle(method: HttpMethod) -> None: ...
+      handle(HttpMethod.GET) # this should be considered OK, because HttpMethod.GET is JUST a raw string literal exactly "GET", and HttpMethod is synonymous with Literal["GET", "POST"]
+      ```
+    - comparing an `Enum` member against a `Literal` type hint currently fails, and I think this is one thing @Randolf Sholz was trying to address with his PEP 586 amendment
+4. **Iteration and containment**: `x in FieldType` and `for x in FieldType` should be first-class
+    - ```python
+      assert "GET" in HttpMethod   # True because HttpMethod acts as an iterable of the unique values, in first-seen order
+      assert HttpMethod.GET in HttpMethod   # True because HttpMethod acts as an iterable of the unique values, in first-seen order
+      ```
+    - both `Literal` and `Enum` provide ways to do this, but it could be more natural (and as @beauxq suggested, even `Literal` could benefit from `in` support)
+5. **Single source of truth**: if I have to write `"A"` more than once when defining my type, it fails this test
+    - ```python
+      class HttpMethod(LiteralEnum):
+          GET = "GET"
+          POST = "POST"
+      ```
+    - user experience and readability matters
+    - single source of truth == easier to refactor/extend/edit == less error prone
+6. **One type, not two**: most current solutions require separate variables for different parts of the functionality, which I find error-prone
+    - ```python
+      def handle(method: HttpMethod) -> None:
+          assert method in HttpMethod
+          if method == HttpMethod.GET:
+            return
+      ```
+    - user experience and readability matters
+    - minimizing number of imports improves user eperience
+    - if there is one type for typehinting, another for iteration/validation, and a third for namespace, it is very easy to get confused and use the wrong one
+7. **Serializable**: values should pass `json.`
+
+
+Here's how the current approaches score:
+
+| Approach                               | #1 Namespace | #2 Raw lit | #3 Member | #4 Iterate | #5 Single source | #6 One type that does it all |
+|----------------------------------------|--------------|------------|-----------|------------|------------------|------------------------------|
+| `Literal` alone                        | ❌            | ✅          | ❌         | ❌          | ✅                | ❌                            |
+| `Literal` + `get_args` (@peter)        | ❌            | ✅          | ❌         | ✅          | ✅                | ❌                           |
+| `StrEnum`                              | ✅            | ❌          | ✅         | ✅          | ✅                | ❌                            |
+| `StrEnum` + PEP 586 amend (@Randolf)   | ✅            | ❌          | ✅         | ✅          | ✅                | ❌                            |
+| `Enum` + `ParamOf` (@Tinche)           | ✅            | ✅          | ✅         | ✅          | ✅                | ❌                            |
+| `Final` class + `Literal` alias (@tmk) | ✅            | ⚠️         | ✅         | ⚠️         | ❌                | ❌                           |
+| Runtime `in` on `Literal` (@beauxq)    | ❌            | ✅          | ❌         | ⚠️         | ✅                | ❌                            |
+| **LiteralEnum (proposed)**             | ✅            | ✅          | ✅         | ✅          | ✅                | ✅                            |
+