Lightweight ORM for Redis
Project description
Installation
Using PyPi (recommended):
sudo pip install redisca
or
wget https://pypi.python.org/packages/source/r/redisca/redisca-X.tar.gz tar xvf redisca-X.tar.gz sudo python redisca-X/setup.py install
Model
from redisca import Model
from redisca import Email
from redisca import DateTime
class User (Model):
email = Email(
field='eml', # Define link with 'eml' hash key.
index=True, # Index support.
unique=True, # Makes sure that field is unique across db.
)
created = DateTime(
field='created', # Define link with 'created' hash key.
new=datetime.utcnow(), # Value which is used as default in User.new()
)
age = Integer(
field='age', # Define link with 'age' hash key.
index=True, # Enable index.
)
user = User.new() # Create model with random id and "new" fields values.
user.getid() # user id
user.email = 'foo@bar.com'
user.save() # Saving routines
user.exists() # True
user.delete() # Deletion routines
user.exists() # False
Fields
Field is the way how you should control data in your models. Just define class variables with field-specific options and take classic ORM’s advantages:
data validation;
native python data types support;
transparent relations between models;
indexes support (incl. unique indexes).
Available parameters:
field - hash field to store value in.
index - makes field searchable.
unique - tells that value should be unique across database. Model.save() will raise an Exception if model of same class already exists with given value.
new - field value which is used as default in Model.new()
Built-in fields:
String - extends IndexField with additional parameters minlen and maxlen.
Email - extends IndexField field with email validation support.
Integer - extends RangeIndexField with parameters minval and maxval. Accepts int and numeric strings. Returns int.
Reference - extends IndexField with cls (reference class) parameter. Accepts and returns instance of cls.
MD5Pass - extends String field. Acts like string but converts given string to md5 sum.
DateTime - extends RangeIndexField without additional parameters. Accepts datetime and int(timestamp) values. Returns datetime.
Getting Data
Using id
Here is an example how to get model instance using id (empty model returned if it not exists yet):
user = User('user id')
print(user.email) # 'foo@bar.com'
Each initialized model is saved in registry and returned on each attempt of re-init:
user1 = User('user_id')
user2 = User('user_id')
user1 is user2 # Always is True
user.free() # Unregister model instance.
User.free_all() # Cleanup User's registry.
Model.free_all() # Unregister all known models.
Find by Index
users = User.email.find('foo@bar.com') # List of matched models
Subclasses of RangeIndexField has a limited support for ranged queries:
users = User.age.range(minval=0, maxval=100, start=50, num=10)
Such call is equivalent of:
SELECT * FROM `users` where `age` BETWEEN 0 AND 100 LIMIT 10 OFFSET 50;
Dict API
All fields are linked to model dict keys. Use can use model dict API to read and write redis hash data AS IS:
user = User('id')
user['eml'] = 'foo@bar.com'
user['age'] = 10
Connecting to Redis
Global database connection setup looks like this:
from redisca import conf
from redis import Redis
conf.db = Redis()
Note: redisca uses localhost:6379(0) as default database. You can setup inheritable per-model database connection using conf class decorator:
from redisca import Model
from redisca import conf
from redis import Redis
@conf(db=Redis())
class User (Model):
pass
Key Format
Model key format is:
model_key_prefix:model_id
Default model_key_prefix is lowercased class name. Use conf class decorator to override it like this:
from redisca import Model
from redisca import conf
@conf(prefix='usr')
class User (Model):
pass
print(User.getprefix()) # 'usr'
print(user.getkey()) # 'usr:1'
Tools
ID Generator
from redisca import hexid
from redisca import intid
print(hexid()) # 59d369790
print(hexid()) # 59d3697bc
print(intid()) # 24116751882
print(intid()) # 24116788848
Flask Support
from redisca import FlaskRedisca
app = Flask()
app.config['REDISCA'] = {
# redis.StrictRedis constructor kwargs dict.
}
FlaskRedisca(app)
Pass optional autosave=True parameter to FlaskRedisca constructor and redisca will save all known models at the end of request. Unchanged and deleted instances are ignored. If you want to skip locally changed instances use free() method during request life.
Requirements
redis-py 2.7+
python 2.7/3.2+ or pypy 2.1+
Python 3.x support
Py3k support is still a sort of experiment but I’m looking carefuly into full compability with cutting-edge builds of CPython. There are no known issues with it actually.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.