more doc work, try fix oracle CI

bckohan · bckohan · commit 9f213b3c326b · 2024-09-07T12:29:46.000-07:00
diff --git a/doc/source/best_practices.rst b/doc/source/best_practices.rst
diff --git a/doc/source/examples.rst b/doc/source/examples.rst
@@ -27,29 +27,30 @@ implement our style enumeration like so:
 
 .. code-block:: python
 
+    import typing as t
     from django.db import models
-    from django_enum import IntegerChoices, EnumField
-    from enum_properties import p, s
+    from django_enum import EnumField
+    from enum_properties import IntEnumProperties, Symmetric
 
     class Map(models.Model):
 
-        class MapBoxStyle(
-            IntegerChoices,
-            s('slug', case_fold=True),
-            p('version')
-        ):
+        class MapBoxStyle(IntEnumProperties):
             """
             https://docs.mapbox.com/api/maps/styles/
             """
-            _symmetric_builtins_ = ['name', 'uri', 'label']
+            _symmetric_builtins_ = ['name', 'uri']
 
-            # name             value    label                 slug         version
-            STREETS           =  1,   'Streets',            'streets',           11
-            OUTDOORS          =  2,   'Outdoors',           'outdoors',          11
-            LIGHT             =  3,   'Light',              'light',             10
-            DARK              =  4,   'Dark',               'dark',              10
+            label: t.Annotated[str, Symmetric()]
+            slug: t.Annotated[str, Symmetric(case_fold=True)]
+            version: int
+
+            # name             value    label                 slug          version
+            STREETS           =  1,   'Streets',            'streets',           12
+            OUTDOORS          =  2,   'Outdoors',           'outdoors',          12
+            LIGHT             =  3,   'Light',              'light',             11
+            DARK              =  4,   'Dark',               'dark',              11
             SATELLITE         =  5,   'Satellite',          'satellite',          9
-            SATELLITE_STREETS =  6,   'Satellite Streets',  'satellite-streets', 11
+            SATELLITE_STREETS =  6,   'Satellite Streets',  'satellite-streets', 12
             NAVIGATION_DAY    =  7,   'Navigation Day',     'navigation-day',     1
             NAVIGATION_NIGHT  =  8,   'Navigation Night',   'navigation-night',   1
 
@@ -88,12 +89,12 @@ We can use our enumeration like so:
 
     map = Map.objects.create()
 
-    map.style.uri == 'mapbox://styles/mapbox/streets-v11'
+    assert map.style.uri == 'mapbox://styles/mapbox/streets-v11'
 
     # uri's are symmetric
     map.style = 'mapbox://styles/mapbox/light-v10'
     map.full_clean()
-    assert map.style == Map.MapBoxStyle.LIGHT
+    assert map.style is Map.MapBoxStyle.LIGHT
     assert map.style == 3
     assert map.style == 'light'
 
diff --git a/doc/source/flag_enums.rst b/doc/source/flag_enums.rst
@@ -0,0 +1,11 @@
+.. include:: refs.rst
+
+.. _flags:
+
+======================
+Flag Enums (bit masks)
+======================
+
+Python Enum_ classes can also be used to represent
+`bit masks <https://en.wikipedia.org/wiki/Mask_(computing)>`_. These types inherit from the Flag_
+extension to Enum_. For example we can define a set of flags for a user's permissions:
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -7,7 +7,6 @@ Django Enum
 |MIT license| |Ruff| |PyPI version fury.io| |PyPI pyversions| |PyPi djversions| |PyPI status|
 |Documentation Status| |Code Cov| |Test Status|
 
-----
 
 |Postgres| |MySQL| |MariaDB| |SQLite| |Oracle|
 
@@ -308,6 +307,7 @@ Please report bugs and discuss features on the
    :caption: Contents:
 
    usage
+   flag_enums
    examples
    performance
    eccentric_enums
diff --git a/doc/source/performance.rst b/doc/source/performance.rst
@@ -2,9 +2,9 @@
 
 .. _performance:
 
-==========================
-Performance Considerations
-==========================
+===========
+Performance
+===========
 
 Enums
 =====
@@ -34,9 +34,14 @@ or eccentric enumeration cases.
 Flags
 =====
 
-The typical flag-like data model is to use a separate boolean column for each
-flag. **Using a flag** ``EnumField`` **out performs boolean columns in both
-storage and query performance in all scenarios.**
+The usual advice for adding bit mask behavior to a database table is to add multiple boolean
+columns. These columns can be indexed together which can speed up certain kinds of queries.
+There is an obvious storage improvement when using a single column bit mask instead, but can
+we achieve better query performance as well? The following benchmarks compare storage and query
+performance between boolean columns and bit masks.
+
+**Using a flag** ``EnumField`` **out performs boolean columns in both
+storage and query performance in most scenarios.**
 
 .. note::
 
@@ -45,7 +50,8 @@ storage and query performance in all scenarios.**
     tables with boolean columns have exactly the same mask values as the tables
     with bitmasks. 10 queries are performed and averaged at each check point.
     Each query generates a different random mask value to query and each table
-    both boolean and bitmask are queried with the same mask value.
+    both boolean and bitmask are queried with the same mask value. The benchmarks
+    were run on an Apple M1 laptop with 16GB of RAM and a 1TB SSD.
 
 
 No Indexing
@@ -60,10 +66,10 @@ for each supported RDBMS. The oracle line shows extents which are allocated in
 .. figure:: plots/FlagSizeBenchmark.png
    :alt: Storage Efficiency improvement over boolean columns
 
-   Storage efficiency improvement over boolean columns. The x-axis is the
-   number of flags and the y-axis is the number of bytes saved per row by using
-   a bitmask instead of a boolean column for each flag. The colored areas show
-   the column type employed to store the bitmask given the number of flags.
+   Storage efficiency improvement over boolean columns. The x-axis is the number of flags and the
+   y-axis is the number of bytes saved per row by using a bitmask instead of a boolean column for
+   each flag. The colored areas show the column type employed to store the bitmask given the number
+   of flags.
 
 For example, using PostgreSQL a table with a 32-flag column will save ~25 bytes
 per row over an equivalent table with 32 boolean columns. *For a table with a
diff --git a/doc/source/reference.rst b/doc/source/reference.rst
@@ -66,3 +66,21 @@ Serializer Fields
    :show-inheritance:
    :private-members:
 
+
+URLs
+----
+
+.. automodule:: django_enum.urls
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
+
+utilities
+---------
+
+.. automodule:: django_enum.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+   :private-members:
diff --git a/tests/test_flags.py b/tests/test_flags.py
@@ -462,5 +462,11 @@ def test_extra_big_flags(self):
             self.assertTrue(obj.extra_big_neg is None)
         self.assertEqual(obj.extra_big_pos, 0)
 
-        self.assertEqual(obj, self.MODEL_CLASS.objects.get(extra_big_pos=0))
+        if connection.vendor == "oracle":
+            # TODO - possible to fix this?
+            self.assertEqual(
+                obj, self.MODEL_CLASS.objects.get(extra_big_pos__isnull=True)
+            )
+        else:
+            self.assertEqual(obj, self.MODEL_CLASS.objects.get(extra_big_pos=0))
         self.assertEqual(obj, self.MODEL_CLASS.objects.get(extra_big_neg__isnull=True))
