Fix JSON property index.

fantix · fantix · commit 7781848cf035 · 2020-05-04T11:08:23.000-05:00
* also support JSON property on non-crud base * add docs for JSON property * fixes #661 * add prop_name type check
diff --git a/docs/how-to/json-props.rst b/docs/how-to/json-props.rst
@@ -0,0 +1,157 @@
+JSON Property
+=============
+
+GINO provides additional support to leverage native JSON type in the database as
+flexible GINO model fields.
+
+Quick Start
+-----------
+
+::
+
+    from gino import Gino
+    from sqlalchemy.dialects.postgresql import JSONB
+
+    db = Gino()
+
+    class User(db.Model):
+        __tablename__ = "users"
+
+        id = db.Column(db.Integer, primary_key=True)
+        name = db.Column(db.String)
+        profile = db.Column(JSONB, nullable=False, server_default="{}")
+
+        age = db.IntegerProperty()
+        birthday = db.DateTimeProperty()
+
+The ``age`` and ``birthday`` are JSON properties stored in the ``profile`` column. You
+may use them the same way as a normal GINO model field::
+
+    u = await User.create(name="daisy", age=18)
+    print(u.name, u.age)  # daisy 18
+
+.. note::
+
+    ``profile`` is the default column name for all JSON properties in a model. If you
+    need a different column name for some JSON properties, you'll need to specify
+    explicitly::
+
+        audit_profile = db.Column(JSON, nullable=False, server_default="{}")
+
+        access_log = db.ArrayProperty(prop_name="audit_profile")
+        abnormal_detected = db.BooleanProperty(prop_name="audit_profile")
+
+Using JSON properties in queries is supported::
+
+    await User.query.where(User.age > 16).gino.all()
+
+This is simply translated into a native JSON query like this:
+
+.. code-block:: plpgsql
+
+    SELECT users.id, users.name, users.profile
+    FROM users
+    WHERE CAST((users.profile ->> $1) AS INTEGER) > $2;  -- ('age', 16)
+
+Datetime type is very much the same::
+
+    from datetime import datetime
+
+    await User.query.where(User.birthday > datetime(1990, 1, 1)).gino.all()
+
+And the generated SQL:
+
+.. code-block:: plpgsql
+
+    SELECT users.id, users.name, users.profile
+    FROM users
+    WHERE CAST((users.profile ->> $1) AS TIMESTAMP WITHOUT TIME ZONE) > $2
+    -- ('birthday', datetime.datetime(1990, 1, 1, 0, 0))
+
+Here's a list of all the supported JSON properties:
+
++----------------------------+-----------------------------+-------------+---------------+
+| JSON Property              | Python type                 | JSON type   | Database Type |
++============================+=============================+=============+===============+
+| :class:`.StringProperty`   | :class:`str`                | ``string``  | ``text``      |
++----------------------------+-----------------------------+-------------+---------------+
+| :class:`.IntegerProperty`  | :class:`int`                | ``number``  | ``int``       |
++----------------------------+-----------------------------+-------------+---------------+
+| :class:`.BooleanProperty`  | :class:`bool`               | ``boolean`` | ``boolean``   |
++----------------------------+-----------------------------+-------------+---------------+
+| :class:`.DateTimeProperty` | :class:`~datetime.datetime` | ``string``  | ``text``      |
++----------------------------+-----------------------------+-------------+---------------+
+| :class:`.ObjectProperty`   | :class:`dict`               | ``object``  | JSON          |
++----------------------------+-----------------------------+-------------+---------------+
+| :class:`.ArrayProperty`    | :class:`list`               | ``array``   | JSON          |
++----------------------------+-----------------------------+-------------+---------------+
+
+
+Hooks
+-----
+
+JSON property provides 2 instance-level hooks to customize the data::
+
+    class User(db.Model):
+        __tablename__ = "users"
+
+        id = db.Column(db.Integer, primary_key=True)
+        profile = db.Column(JSONB, nullable=False, server_default="{}")
+
+        age = db.IntegerProperty()
+
+        @age.before_set
+        def age(self, val):
+            return val - 1
+
+        @age.after_get
+        def age(self, val):
+            return val + 1
+
+    u = await User.create(name="daisy", age=18)
+    print(u.name, u.profile, u.age)  # daisy {'age': 17} 18
+
+And 1 class-level hook to customize the SQLAlchemy expression of the property::
+
+    class User(db.Model):
+        __tablename__ = "users"
+
+        id = db.Column(db.Integer, primary_key=True)
+        profile = db.Column(JSONB, nullable=False, server_default="{}")
+
+        height = db.JSONProperty()
+
+        @height.expression
+        def height(cls, exp):
+            return exp.cast(db.Float)  # CAST(profile -> 'height' AS FLOAT)
+
+
+Create Index on JSON Properties
+-------------------------------
+
+We'll need to use :meth:`~gino.declarative.declared_attr` to wait until the model class
+is initialized. The rest is very much the same as defining a usual index::
+
+    class User(db.Model):
+        __tablename__ = "users"
+
+        id = db.Column(db.Integer, primary_key=True)
+        profile = db.Column(JSONB, nullable=False, server_default="{}")
+
+        age = db.IntegerProperty()
+
+        @db.declared_attr
+        def age_idx(cls):
+            return db.Index("age_idx", cls.age)
+
+This will lead to the SQL below executed if you run ``db.gino.create_all()``:
+
+.. code-block:: plpgsql
+
+    CREATE INDEX age_idx ON users (CAST(profile ->> 'age' AS INTEGER));
+
+.. warning::
+
+    Alembic doesn't support auto-generating revisions for functional indexes yet. You'll
+    need to manually edit the revision. Please follow `this issue
+    <https://github.com/sqlalchemy/alembic/issues/676>`__ for updates.
diff --git a/src/gino/crud.py b/src/gino/crud.py
@@ -435,14 +435,6 @@ def __init__(self, **values):
     @classmethod
     def _init_table(cls, sub_cls):
         rv = Model._init_table(sub_cls)
-        for each_cls in sub_cls.__mro__[::-1]:
-            for k, v in each_cls.__dict__.items():
-                if isinstance(v, json_support.JSONProperty):
-                    if not hasattr(sub_cls, v.prop_name):
-                        raise AttributeError(
-                            'Requires "{}" JSON[B] column.'.format(v.prop_name)
-                        )
-                    v.name = k
         if rv is not None:
             rv.__model__ = weakref.ref(sub_cls)
         return rv
diff --git a/src/gino/declarative.py b/src/gino/declarative.py
@@ -3,6 +3,7 @@
 import sqlalchemy as sa
 from sqlalchemy.exc import InvalidRequestError
 
+from . import json_support
 from .exceptions import GinoException
 
 
@@ -75,6 +76,8 @@ def invert_get(self, value, default=None):
 class Dict(collections.OrderedDict):
     def __setitem__(self, key, value):
         if isinstance(value, sa.Column) and not value.name:
+            value.name = value.key = key
+        if isinstance(value, json_support.JSONProperty) and not value.name:
             value.name = key
         return super().__setitem__(key, value)
 
@@ -272,7 +275,7 @@ def _init_table(cls, sub_cls):
                 if isinstance(v, sa.Column):
                     v = v.copy()
                     if not v.name:
-                        v.name = k
+                        v.name = v.key = k
                     column_name_map[k] = v.name
                     columns.append(v)
                     updates[k] = sub_cls.__attr_factory__(k, v)
@@ -311,6 +314,21 @@ def _init_table(cls, sub_cls):
         rv = sa.Table(table_name, sub_cls.__metadata__, *args, **table_kw)
         for k, v in updates.items():
             setattr(sub_cls, k, v)
+        for each_cls in sub_cls.__mro__[::-1]:
+            for k, v in each_cls.__dict__.items():
+                if isinstance(v, json_support.JSONProperty):
+                    json_col = getattr(
+                        sub_cls.__dict__.get(v.prop_name), "column", None
+                    )
+                    if not isinstance(json_col, sa.Column) or not isinstance(
+                        json_col.type, sa.JSON
+                    ):
+                        raise AttributeError(
+                            '{} "{}" requires a JSON[B] column "{}" '
+                            "which is not found or has a wrong type.".format(
+                                type(v).__name__, v.name, v.prop_name,
+                            )
+                        )
         return rv
 
 
diff --git a/tests/test_json.py b/tests/test_json.py
@@ -230,6 +230,21 @@ class Test(db.Model):
 
             age = db.IntegerProperty(default=18)
 
+    with pytest.raises(AttributeError, match=r"JSON\[B\] column"):
+        # noinspection PyUnusedLocal,PyRedeclaration
+        class Test(db.Model):
+            __tablename__ = "tests_no_profile"
+
+            profile = db.StringProperty()
+
+    with pytest.raises(AttributeError, match=r"JSON\[B\] column"):
+        # noinspection PyUnusedLocal,PyRedeclaration
+        class Test(db.Model):
+            __tablename__ = "tests_no_profile"
+
+            profile1 = db.StringProperty(prop_name="profile2")
+            profile2 = db.IntegerProperty(prop_name="profile1")
+
 
 async def test_t291_t402(bind):
     from gino.dialects.asyncpg import JSON, JSONB
@@ -281,3 +296,19 @@ class PathTest(db.Model):
         assert t1.data == t2.data
     finally:
         await PathTest.gino.drop()
+
+
+async def test_index(bind):
+    from gino.dialects.asyncpg import JSONB
+
+    class IndexTest(db.Model):
+        __tablename__ = "index_test"
+        profile = db.Column(JSONB())
+        age = db.IntegerProperty()
+
+        @db.declared_attr
+        def age_idx(cls):
+            return db.Index("age_idx", cls.age)
+
+    await IndexTest.gino.create()
+    await IndexTest.gino.drop()
