Hare

hare是一个基于pymysql并运用ActiveRecord模式的ORM框架, 在虚拟环境下，通过：

pip install hare

即可安装。

当前，它只支持：

MySQL

动机

在Python下进行数据库操作，大体有两种方法：

1、使用raw sql
2、使用ORM

Raw SQL

python中常用的raw sql工具是：

MySQLdb
PyMySQL

使用raw sql的好处是：

给予开发人员极大的自由，让开发人员知道具体要执行的sql，方便sql优化

坏处是麻烦：

写起来麻烦、影响开发速度；维护起来也麻烦

ORM

python中用的最广的ORM是SQLAlchemy和Peewee.

使用ORM的好处是：

写起来方便，维护方便

坏处是：

对开发人员透明、不利于sql优化；
主流的ORM学习成本高，对于一般的中小型项目而言，用不到那么到功能，如SQLAlchemy

此外， pythonORM框架的使用哲学是：

需要要手动的在类中配置字段和对应类型， 然后使用ORM去自动创建对应的table。

而开发人员的哲学是:

手动使用sql建表、然后再去创建对应的ORM。

那么，比较下来，就产生了新的需求：实现一个ORM，满足下列要求：

1、方便ORM和数据库表之间的映射、最好不用在ORM中声明字段
2、支持raw sql
3、不需要实现复杂的API(太复杂的，可以直接通过raw sql实现)
4、支持事务(声明式、命令式)

很容易想到，使用Active Record的方式实现一个ORM，满足上述条件

于是就实现了一个名为Hare的ORM.Hare的意思是野兔，希望进行python的db操作时，像兔子一样快。

参考框架

在设计和实现Hare的过程中，参考了Flask框架和jFinal框架的设计。

jFinal

jFinal是一种轻量的java web框架；设计和实现Hare的过程中，借鉴了它的一些设计思想：

自动获取表结构

jFinal在启动的时候，根据ORM对应的表名，通过MySQL的INFORMATION_SCHEMA取获取表结构； Hare也通过此方式来获取。

Flask

Flask是一种轻量的python web框架；设计和实现Hare的过程中，借鉴了它的一些设计思想：

将框架对象化

flask中，通过：

app = Flask(__name__)

的方式来建立一个应用对象，并在该对象中存储相关路由、处理器等信息；

Hare中，采用类似方式，通过：

haredb = Hare(host='localhost', user='root',
          password='*****', db='test',
          charset='utf8')

来创建一个数据源对象，存放数据操作所需的一切信息。

装饰器

flask中，使用装饰器的方式，来定义路由处理：

@app.route('/home', methods=['GET'])
def home():
    pass

Hare也使用装饰器来定义定义数据模型类和表之间的映射关系，并存储，如下：

@haredb.table('user')
class User(haredb.Model):
    pass

把User类和user表对应起来.

同时，Hare中的事务也可以通过装饰器来实现：

@haredb.tx
def func(...):
    ...

使用

数据库的"库->表->字段"，是一种层次分明的结构。Hare也基于此。

用户提供数据库的连接配置，就对应了一个数据源，也就是Database；

haredb = Hare(
        host='localhost', user='root',
        password='********', db='test',
        charset='utf8')

假设在test数据库中已经创建了一个user表：

USER_TABLE = """CREATE TABLE `user` (
              `uid` int(11) NOT NULL AUTO_INCREMENT,
              `nickname` varchar(20) DEFAULT NULL,
              `email` varchar(20) DEFAULT NULL,
              PRIMARY KEY (`uid`)
            ) ENGINE=InnoDB AUTO_INCREMENT=59 DEFAULT CHARSET=utf8"""

通过装饰器来声明这个数据库下有哪些表(添加一个名是user的table，对应的模型是User)：

@haredb.table('user')
class User(haredb.Model):
    pass

那么:

完整的用例如下

#! -*- coding: utf-8 -*-
from __future__ import absolute_import
import logging
from traceback import format_exc
from hare import Hare

# 创建一个Hare对象, 作为数据源
# 会使用默认的logger来记录执行的sql
haredb = Hare(
    host='localhost', user='root',
    password='********', db='test',
    charset='utf8')
    
# 创建一个自定义logger的数据源
logger = logging.getLogger('hare')
logger.addHandler(logging.StreamHandler())
logger.setLevel(logging.DEBUG)
haredb = Hare(
    host='localhost', user='root',
    password='********', db='test',
    charset='utf8',
    logger=logger)

# 将user表和User类绑定
@haredb.table('user')
class User(haredb.Model):
    pass
    
# 获取所有的表名
# 返回['user']
print haredb.tables

 
# 获取User类对应的table对象
table = User.table

# 输出表名称
print table.name

# 清空User表
table.truncate()

# 判断字段是否属于该表
print table.is_column('uid')
print table.is_column('uid_not_exists')

# 新建一条记录
u = User()
u.set_many(**{'nickname': 'haha', 'email': 'a@q.com'}).save()

# 获取主键
print u.uid

# 获取一条记录
u = User.get(uid=1)

# 修改字段的值
u.nickname = 'new name'
u.update()

# 删除该对象
u.delete()

# 获取所有的用户记录
# 每个元素是个dict
users = User.select_many()

# 查询符合条件的所有记录
# 每个元素是个dict
users = User.select_many(email='a@q.com')

# 分页查询User表
pagination = User.paginate(params={'nickname': ('is not', None)}, page=1, per_page=10)
print pagination.items

# 获取一条数据库连接
dbi = haredb.dbi

# 执行row sql
# 一条记录
users = dbi.select(u'SELECT * FROM user WHERE uid = 10')
# 多条记录
users = dbi.select_many(u'SELECT * FROM user WHERE uid > 10')
# 执行写操作
dbi.modify(u'DELETE FROM user WHERE uid = %s', 1)
# 批量写操作
rows = [{'nickname': 'test', 'email': 'test@qq.com'}]
dbi.modify_many(u'INSERT INTO user(nickname, email) VALUES(%(nickname)s, %(email)s)', rows)

# 执行事务
@haredb.tx
def save_user():
    user = User().set_many(**{'nickname': 'test2'})
    user.save()
    # 1/0 取消注释该行，则保存失败
    
# 执行事务的另外一种方式
def save_user2():
    user = User().set_many(**{'nickname': 'test2'})
    user.save()
    # 1/0 取消注释该行，则保存失败

with haredb.get_tx() as tx:
    try:
        save_user2()
    except:
        logging.error(format_exc())
        tx.rollback()
    else:
        tx.commit()
print User.select_many()

API

见

doc/api.md

个人博客

bingtel-木犹如此

bingtel / hare

Hare

动机

Raw SQL

ORM

参考框架

jFinal

自动获取表结构

Flask

将框架对象化

装饰器

使用

完整的用例如下

API

个人博客

简介

发行版

贡献者

近期动态

bingtel / hare .gitee-modal { width: 500px !important; }

Hare

动机

Raw SQL

ORM

参考框架

jFinal

自动获取表结构

Flask

将框架对象化

装饰器

使用

完整的用例如下

API

个人博客

简介

发行版

开源评估指数源自 OSS-Compass 评估体系，评估体系围绕以下三个维度对项目展开评估：

贡献者

近期动态

搜索帮助

bingtel / hare