redis-om-python/README.md

207 lines
5.4 KiB
Markdown
Raw Normal View History

# Redis Developer Python
redis-developer-python is a high-level library containing useful Redis
abstractions and tools, like an ORM and leaderboard.
## ORM/ODM
redis-developer-python includes an ORM/ODM.
### Declarative model classes
```pyhon
import decimal
import datetime
from typing import Optional
from redis import Redis
from redis_developer.orm import (
RedisModel,
Field,
Relationship
)
db = Redis()
# Declarative model classes
class BaseModel(RedisModel):
config:
database = db
class Address(BaseModel):
address_line_1: str
address_line_2: str
city: str
country: str
postal_code: str
class Order(BaseModel):
total: decimal.Decimal
currency: str
created_on: datetime.datetime
class Member(BaseModel):
# An auto-incrementing primary key is added by default if no primary key
# is specified.
id: Optional[int] = Field(default=None, primary_key=True)
first_name: str
last_name: str
email: str = Field(unique=True, index=True)
zipcode: Optional[int]
join_date: datetime.date
# Creates an embedded document: stored as hash fields or JSON document.
address: Address
# Creates a relationship to data in separate Hash or JSON documents.
orders: Relationship(Order, backref='recommended',
field_name='recommended_by')
# Creates a self-relationship.
recommended_by: Relationship('Member', backref='recommended',
field_name='recommended_by')
class Meta:
key_pattern = "member:{id}"
# Validation
# Raises ValidationError: last_name is required
Member(
first_name="Andrew",
zipcode="97086",
join_date=datetime.date.today()
)
# Passes validation
Member(
first_name="Andrew",
last_name="Brookins",
zipcode="97086",
join_date=datetime.date.today()
)
# Raises ValidationError: zipcode is not a number
Member(
first_name="Andrew",
last_name="Brookins",
zipcode="not a number",
join_date=datetime.date.today()
)
# Persist a model instance to Redis
member = Member(
first_name="Andrew",
last_name="Brookins",
zipcode="97086",
join_date=datetime.date.today()
)
# Assign the return value to get any auto-fields filled in,
# like the primary key (if an auto-incrementing integer).
member = member.save()
# Hydrate a model instance from Redis using the primary key.
member = Member.get(d=1)
# Hydrate a model instance from Redis using a secondary index on a unique field.
member = Member.get(email="a.m.brookins@gmail.com")
# What if the field wasn't unique and there were two "a.m.brookins@gmail.com"
# entries?
# This would raise a MultipleObjectsReturned error:
member = Member.get(Member.email == "a.m.brookins@gmail.com")
# What if you know there might be multiple results? Use filter():
members = Member.filter(Member.last_name == "Brookins")
# What if you want to only return values that don't match a query?
members = Member.exclude(last_name="Brookins")
# You can combine filer() and exclude():
members = Member.filter(last_name="Brookins").exclude(first_name="Andrew")
```
### Serialization and validation based on model classes
### Save a model instance to Redis
### Get a single model instance from Redis
### Update a model instance in Redis
### Batch/bulk insert and updates
### Declarative index creation and automatic index management
### Declarative “primary key”
### Declarative relationships (via Sorted Sets) or Embedded documents (JSON)
### Exact-value queries on indexed fields
### Ad-hoc numeric range and full-text queries (RediSearch)
### Aggregations (RediSearch)
### Unanswered Questions
What's the difference between these two forms?
```python
from redis_developer.orm import (
RedisModel,
indexed,
unique
)
class Member(RedisModel):
email: unique(str)
email: indexed(str)
# email: Indexed[str] <- Probably not possible?
# email: IndexedStr <- This is how constrained types work in Pydantic
class Meta:
primary_key = "id"
indexes = ["email"] # <- How about this?
```
It appears that Pydantic uses functions when declaring the type requires some
kind of parameter. E.g., the max and min values for a constrained numeric
field.
Indexing probably requires, in some cases, parameters... so it should be a
function, probably. And in general, function vs. class appears to be only a case
of whether parameters are required.
1. unique() and indexed() require lots of work.
2. IndexedStr - what does that even mean exactly?
3. indexes = [] - Here, we could hook into class-level validation and add logic
to make sure that any indexed values were unique. Right?
### Unique checking
When is the right time to check if e.g. an email field is unique in Redis?
If we check on instantiation of the model, we'll still need to check again when
we save the model.
### Field() vs constrained int, etc.
Pydantic includes field helpers like constr, etc. that apply a schema to values.
On top of that, we'll have a Field() helper that includes options common to all
data types possible for a field.
This is where we'll track if we should index a field, verify uniqueness, etc.
But for facts like numeric constraints, we'll rely on Pydantic.
### Automatic fields
Redis doesn't have server-side automatic values, dates, etc. So we don't need to
worry about refreshing from the server to get the automatically-created values.
As soon as someone saves a model, we, the ORM, will have created the automatic
values, so we can just set them in the model instance.