Final docs push

Author: Andrew Brookins

README.md

@@ -113,7 +113,7 @@ andrew = Customer(
 # The model generates a globally unique primary key automatically
 # without needing to talk to Redis.
 print(andrew.pk)
-# > '01FJM6PH661HCNNRC884H6K30C'
+# > "01FJM6PH661HCNNRC884H6K30C"
 
 # We can save the model to Redis by calling `save()`:
 andrew.save()
@@ -199,7 +199,6 @@ from redis_om import (
     HashModel,
     Migrator
 )
-from redis_om import get_redis_connection
 
 
 class Customer(HashModel):
@@ -217,8 +216,7 @@ class Customer(HashModel):
 # Before running queries, we need to run migrations to set up the
 # indexes that Redis OM will use. You can also use the `migrate`
 # CLI tool for this!
-redis = get_redis_connection()
-Migrator(redis).run()
+Migrator().run()
 
 # Find all customers with the last name "Brookins"
 Customer.find(Customer.last_name == "Brookins").all()
@@ -253,7 +251,6 @@ from redis_om import (
     Field,
     Migrator,
 )
-from redis_om import get_redis_connection
 
 
 class Address(EmbeddedJsonModel):
@@ -284,8 +281,7 @@ class Customer(JsonModel):
 # Before running queries, we need to run migrations to set up the
 # indexes that Redis OM will use. You can also use the `migrate`
 # CLI tool for this!
-redis = get_redis_connection()
-Migrator(redis).run()
+Migrator().run()
 
 # Find all customers who live in San Antonio, TX
 Customer.find(Customer.address.city == "San Antonio",

aredis_om/model/cli/migrate.py

@@ -7,6 +7,7 @@
 @click.option("--module", default="aredis_om")
 def migrate(module):
     migrator = Migrator(module)
+    migrator.detect_migrations()
 
     if migrator.migrations:
         print("Pending migrations:")

aredis_om/model/encoders.py

@@ -68,6 +68,15 @@ def jsonable_encoder(
         include = set(include)
     if exclude is not None and not isinstance(exclude, (set, dict)):
         exclude = set(exclude)
+
+    if custom_encoder:
+        if type(obj) in custom_encoder:
+            return custom_encoder[type(obj)](obj)
+        else:
+            for encoder_type, encoder in custom_encoder.items():
+                if isinstance(obj, encoder_type):
+                    return encoder(obj)
+
     if isinstance(obj, BaseModel):
         encoder = getattr(obj.__config__, "json_encoders", {})
         if custom_encoder:
@@ -145,13 +154,9 @@ def jsonable_encoder(
             )
         return encoded_list
 
-    if custom_encoder:
-        if type(obj) in custom_encoder:
-            return custom_encoder[type(obj)](obj)
-        else:
-            for encoder_type, encoder in custom_encoder.items():
-                if isinstance(obj, encoder_type):
-                    return encoder(obj)
+    # This function originally called custom encoders here,
+    # which meant we couldn't override the encoder for many
+    # types hard-coded into this function (lists, etc.).
 
     if type(obj) in ENCODERS_BY_TYPE:
         return ENCODERS_BY_TYPE[type(obj)](obj)

aredis_om/model/migrations/migrator.py

@@ -84,12 +84,11 @@ async def drop(self):
 
 
 class Migrator:
-    def __init__(self, redis: Redis, module=None):
+    def __init__(self, module=None):
         self.module = module
         self.migrations: List[IndexMigration] = []
-        self.redis = redis
 
-    async def run(self):
+    async def detect_migrations(self):
         # Try to load any modules found under the given path or module name.
         if self.module:
             import_submodules(self.module)
@@ -100,6 +99,7 @@ async def run(self):
 
         for name, cls in model_registry.items():
             hash_key = schema_hash_key(cls.Meta.index_name)
+            redis = cls.db()
             try:
                 schema = cls.redisearch_schema()
             except NotImplementedError:
@@ -108,7 +108,7 @@ async def run(self):
             current_hash = hashlib.sha1(schema.encode("utf-8")).hexdigest()  # nosec
 
             try:
-                await self.redis.execute_command("ft.info", cls.Meta.index_name)
+                await redis.execute_command("ft.info", cls.Meta.index_name)
             except ResponseError:
                 self.migrations.append(
                     IndexMigration(
@@ -117,12 +117,12 @@ async def run(self):
                         schema,
                         current_hash,
                         MigrationAction.CREATE,
-                        self.redis,
+                        redis,
                     )
                 )
                 continue
 
-            stored_hash = await self.redis.get(hash_key)
+            stored_hash = await redis.get(hash_key)
             schema_out_of_date = current_hash != stored_hash
 
             if schema_out_of_date:
@@ -134,7 +134,7 @@ async def run(self):
                         schema,
                         current_hash,
                         MigrationAction.DROP,
-                        self.redis,
+                        redis,
                         stored_hash,
                     )
                 )
@@ -145,12 +145,14 @@ async def run(self):
                         schema,
                         current_hash,
                         MigrationAction.CREATE,
-                        self.redis,
+                        redis,
                         stored_hash,
                     )
                 )
 
+    async def run(self):
         # TODO: Migration history
         # TODO: Dry run with output
+        await self.detect_migrations()
         for migration in self.migrations:
             await migration.run()

aredis_om/model/model.py

@@ -107,6 +107,7 @@ def embedded(cls):
 
 
 def is_supported_container_type(typ: Optional[type]) -> bool:
+    # TODO: Wait, why don't we support indexing sets?
     if typ == list or typ == tuple:
         return True
     unwrapped = get_origin(typ)
@@ -479,8 +480,7 @@ def expand_tag_value(value):
         if isinstance(value, str):
             return escaper.escape(value)
         if isinstance(value, bytes):
-            # TODO: We don't decode and then escape bytes objects passed as input.
-            #  Should we?
+            # TODO: We don't decode bytes objects passed as input. Should we?
             # TODO: TAG indexes fail on JSON arrays of numbers -- only strings
             #  are allowed -- what happens if we save an array of bytes?
             return value
@@ -966,15 +966,14 @@ class PrimaryKey:
     field: ModelField
 
 
-class BaseMeta(abc.ABC):
+class BaseMeta(Protocol):
     global_key_prefix: str
     model_key_prefix: str
     primary_key_pattern: str
     database: aioredis.Redis
     primary_key: PrimaryKey
     primary_key_creator_cls: Type[PrimaryKeyCreator]
     index_name: str
-    abstract: bool
     embedded: bool
     encoding: str
 
@@ -994,7 +993,6 @@ class DefaultMeta:
     primary_key: Optional[PrimaryKey] = None
     primary_key_creator_cls: Optional[Type[PrimaryKeyCreator]] = None
     index_name: Optional[str] = None
-    abstract: Optional[bool] = False
     embedded: Optional[bool] = False
     encoding: str = "utf-8"
 
@@ -1269,17 +1267,23 @@ def __init_subclass__(cls, **kwargs):
         super().__init_subclass__(**kwargs)
 
         for name, field in cls.__fields__.items():
+            origin = get_origin(field.outer_type_)
+            if origin:
+                for typ in (Set, Mapping, List):
+                    if issubclass(origin, typ):
+                        raise RedisModelError(
+                            f"HashModels cannot index set, list,"
+                            f" or mapping fields. Field: {name}"
+                        )
+
             if issubclass(field.outer_type_, RedisModel):
                 raise RedisModelError(
-                    f"HashModels cannot have embedded model " f"fields. Field: {name}"
+                    f"HashModels cannot index embedded model fields. Field: {name}"
+                )
+            elif dataclasses.is_dataclass(field.outer_type_):
+                raise RedisModelError(
+                    f"HashModels cannot index dataclass fields. Field: {name}"
                 )
-
-            for typ in (Set, Mapping, List):
-                if issubclass(field.outer_type_, typ):
-                    raise RedisModelError(
-                        f"HashModels cannot have set, list,"
-                        f" or mapping fields. Field: {name}"
-                    )
 
     async def save(self, pipeline: Optional[Pipeline] = None) -> "HashModel":
         self.check()
@@ -1360,6 +1364,8 @@ def schema_for_fields(cls):
         for name, field in cls.__fields__.items():
             # TODO: Merge this code with schema_for_type()?
             _type = field.outer_type_
+            is_subscripted_type = get_origin(_type)
+
             if getattr(field.field_info, "primary_key", None):
                 if issubclass(_type, str):
                     redisearch_field = (
@@ -1372,7 +1378,12 @@ def schema_for_fields(cls):
                 schema_parts.append(redisearch_field)
             elif getattr(field.field_info, "index", None) is True:
                 schema_parts.append(cls.schema_for_type(name, _type, field.field_info))
-            elif is_supported_container_type(_type):
+            elif is_subscripted_type:
+                # Ignore subscripted types (usually containers!) that we don't
+                # support, for the purposes of indexing.
+                if not is_supported_container_type(_type):
+                    continue
+
                 embedded_cls = get_args(_type)
                 if not embedded_cls:
                     # TODO: Test if this can really happen.

docs/getting_started.md

@@ -658,7 +658,6 @@ from pydantic import EmailStr
 
 from redis_om import (
     Field,
-    get_redis_connection,
     HashModel,
     Migrator
 )
@@ -679,8 +678,7 @@ class Customer(HashModel):
 # Before running queries, we need to run migrations to set up the
 # indexes that Redis OM will use. You can also use the `migrate`
 # CLI tool for this!
-redis = get_redis_connection()
-Migrator(redis).run()
+Migrator().run()
 
 # Find all customers with the last name "Brookins"
 Customer.find(Customer.last_name == "Brookins").all()

docs/index.md

@@ -1,6 +1,6 @@
 # Redis OM for Python
 
-Welcome! This is the index of documentation for redis-om-python.
+Welcome! This is the documentation for redis-om-python.
 
 **NOTE**: The documentation is a bit sparse at the moment but will continue to grow!
 
@@ -12,6 +12,10 @@ Read the Getting Started tutorial at [getting_started.md](getting_started.md).
 
 Read about connecting to Redis at [connections.md](connections.md).
 
+## Models and Fields
+
+Learn all about how to create model instances and define fields in [models.md](models.md).
+
 ## Validating Data
 
 Read about how to use Redis OM models to validate data at [validation.md](validation.md)