Flask-邮件发送和数据模型
这篇讲什么
- 前半篇用 Flask-Mail 发邮件:配置必须写在
Mail(app)之前、Message与send()的用法、异步发送的封装,以及测试时靠record_messages不真发。 - 后半篇进 Flask-SQLAlchemy:建表删表、
db.Model的增删改查、字段类型与选项对照表、Alembic 迁移(Flask-Migrate 4.1.0)。 - 实测环境 Flask 3.1.3 + Flask-SQLAlchemy 3.1.1 + SQLAlchemy 2.1.8,邮件那段是拿本机 SMTP 靶子跑出来的。
Flask-Mail 发邮件
-
老笔记这节用的
flask_mail现在仍然是官方生态里的那一个:PyPI 上最新是 0.10.0(2024-05-23 发布),仓库挂在pallets-eco组织下,依赖只有flask和blinker。装法:1
pip install flask-mail
-
配置必须在
Mail(app)之前写好。老笔记那句「必须先写配置,然后再创建Mail对象,否则配置无效」是对的,原因在源码里:init_app会调init_mail(app.config, ...),把所有MAIL_*读成一个固定的 state 挂到app.extensions['mail']。实测:1
2建 Mail 之后再改 config -> state.server='smtp-before.example'(改不动)
再调一次 init_app(app) -> state.server='smtp-after.example' -
配置项与默认值(本机实测):
键 默认值 说明 MAIL_SERVER127.0.0.1SMTP 服务器 MAIL_PORT25端口,TLS 常用 587、SSL 常用 465 MAIL_USE_TLSFalse587 端口用这个 MAIL_USE_SSLFalse465 端口用这个 MAIL_USERNAME/MAIL_PASSWORDNone登录凭据 MAIL_DEFAULT_SENDERNone默认发件人 MAIL_SUPPRESS_SEND等于 testing只测试时设 True,不真发 MAIL_DEBUG等于 app.debugMAIL_MAX_EMAILSNone一次连接最多发几封 MAIL_ASCII_ATTACHMENTSFalse附件名转 ASCII -
用户名和密码走环境变量,不要把明文写进代码:
app.py 1
2
3
4
5
6
7
8
9
10import os
from flask import Flask
from flask_mail import Mail
app = Flask(__name__)
app.config['MAIL_SERVER'] = os.environ.get('MAIL_SERVER', 'smtp.163.com')
app.config['MAIL_USERNAME'] = os.environ.get('MAIL_USERNAME')
app.config['MAIL_PASSWORD'] = os.environ.get('MAIL_PASSWORD')
app.config['MAIL_DEFAULT_SENDER'] = os.environ.get('MAIL_USERNAME')
mail = Mail(app)
发一封真的邮件
1 | from flask_mail import Message |
-
本机起了一个只监听
127.0.0.1的最小 SMTP 桩,真跑一遍抓到的完整会话是:1
2
3
4
5
6
7ehlo [172.30.48.1]
AUTH LOGIN cHJvYmUtdXNlcg==
cHJvYmUtcGFzc3dvcmQ=
mail from:<sender@example.com>
rcpt to:<recv@example.com>
data
quit -
正文 1076 字节,头部长这样(中文主题被编码成 base64 是正常的):
1
2
3
4
5Content-Type: multipart/mixed; boundary="===============5638105417725480875=="
MIME-Version: 1.0
Subject: =?utf-8?b?6LSm5oi35r+A5rS7?=
From: sender@example.com
To: recv@example.combody和html组成multipart/alternative,附件再套一层multipart/mixed,实测两个都在。 -
Message的构造参数是位置敏感的:Message(subject, recipients, sender, body, html),推荐全用关键字。不写sender时取MAIL_DEFAULT_SENDER,两者都没有实测报:1
AssertionError: The message does not specify a sender and a default sender has not been configured
-
附件在 0.10 里不再是元组:实测
msg.attachments里是Attachment对象,字段为data / filename / content_type / disposition / headers,老笔记那种msg.attachments[0][0]的下标写法会TypeError: 'Attachment' object is not subscriptable。
封装与异步发送
-
常见封装是模板渲染加发送:
app.py 1
2
3
4
5
6def send_mail(to, subject, template, **kwargs):
msg = Message(subject, recipients=[to])
msg.html = render_template(template + '.html', **kwargs)
msg.body = render_template(template + '.txt', **kwargs)
mail.send(msg)
return msg所以要准备成对的
activate.html和activate.txt两个模板。 -
发真邮件是慢 IO,放线程里做。这里有个必须理解的点:线程里没有请求上下文,所以不能把
current_app这个代理直接传过去,要取原对象:app.py 1
2
3
4
5
6
7
8
9
10
11
12
13
14
15from threading import Thread
from flask import current_app
def async_send(app_obj, msg):
with app_obj.app_context():
mail.send(msg)
def send_mail_async(to, subject, template, **kwargs):
app_obj = current_app._get_current_object()
msg = Message(subject, recipients=[to])
msg.html = render_template(template + '.html', **kwargs)
msg.body = render_template(template + '.txt', **kwargs)
thr = Thread(target=async_send, args=[app_obj, msg])
thr.start()
return thr -
实测对照:在新线程里直接
Message(...)得到RuntimeError: Working outside of application context.;把current_app._get_current_object()传进去再with app.app_context():就正常。 -
老笔记那段代码里还留着
manager.run(),flask_script已经不能用,启动方式见 Flask-基本入门。
测试与不真发
-
单测里不要连 SMTP,用 Flask-Mail 自带的信号收集:
app.py 1
2
3with mail.record_messages() as outbox:
mail.send(Message('测试主题', recipients=['r@example.com'], body='正文'))
mail.send(Message('第二封', recipients=['s@example.com'], body='b2'))实测
outbox长度 2,元素就是发出去的Message,subject / recipients / html / body都能直接断言。 -
MAIL_SUPPRESS_SEND=True时send()什么都不连也不报错,实测抓不到任何会话。 -
另一个选择是
Flask-Mailman 1.1.1(Django email 后端的移植)。它用的键和 Flask-Mail 是同一套MAIL_*(源码里读MAIL_SERVER、MAIL_PORT、MAIL_USERNAME…),再加一个MAIL_BACKEND;Mail(app, testing=True)会把后端自动切成locmem。网上流传的MAILMAN_*前缀并不存在,别照抄。
Flask-SQLAlchemy
-
Flask-SQLAlchemy 把 SQLAlchemy 接到 Flask 的应用上下文上,本机版本 3.1.1 + SQLAlchemy 2.1.8。装法:
1
pip install flask-sqlalchemy
-
连接串
SQLALCHEMY_DATABASE_URI说的是「用哪个库、怎么连」:数据库 写法 SQLite(Windows) sqlite:///C:/path/to/data.sqliteSQLite(Linux/macOS) sqlite:////path/to/data.sqliteMySQL(官方推荐,C 扩展) mysql+mysqldb://user:password@127.0.0.1:3306/dbname?charset=utf8mb4MySQL(纯 Python 备选) mysql+pymysql://user:password@127.0.0.1:3306/dbname?charset=utf8mb4PostgreSQL postgresql+psycopg://user:password@127.0.0.1:5432/dbname- SQLite 后面那几个斜杠不是笔误:
sqlite:///之后接路径,绝对路径要四个斜杠。 - 老笔记写的
mysql + pymysql://...中间有空格,charset-utf8也少了等号,照抄一定连不上。 - MySQL 驱动按 SQLAlchemy 官方口径用 C 扩展
mysqlclient(连接串里写mysql+mysqldb)。本机 flask 环境实测:pip install mysqlclient直接拿到mysqlclient-2.3.0-cp314的 wheel,不用编译;create_engine('mysql+mysqldb://...')建得起来,dialect.driver是mysqldb。纯 Python 的 PyMySQL 同样实测可用(dialect.driver为pymysql),装不了 C 扩展时用它。 - PyMySQL 的版本别看错:
importlib.metadata.version('pymysql')和pymysql.VERSION都是 1.2.3(包版本),而pymysql.__version__给出的是2.2.8——那是它链接的 MySQL 客户端库版本。写版本号要用前者。 - 取驱动版本别写
MySQLdb.__version__,实测这个属性不存在,要写MySQLdb.version_info(得到(2, 3, 0, 'final', 0))或importlib.metadata.version('mysqlclient')。 - 装法与真实连库的实测见 Django 系列,本系列不重复;连接串里的
password走环境变量,不要把明文写进代码。
- SQLite 后面那几个斜杠不是笔误:
-
初始化有两种写法。实测
SQLAlchemy(app)在 3.1.1 上不报警告,但同一个 app 上注册两次会直接报错:1
2SQLAlchemy(app) -> 建成,警告 0 条
再 init_app(app) -> RuntimeError: A 'SQLAlchemy' instance has already been registered on this Flask app.项目稍大就建议拆成「模块级
db = SQLAlchemy()+ 工厂里db.init_app(app)」,这样模型文件不会反向依赖 app 实例。
建表与删表
1 | import os |
-
create_all()/drop_all()必须在应用上下文里调用,这是 FSA 3.x 的硬要求,实测在上下文外直接:1
RuntimeError: Working outside of application context.
app.py 1
2
3with app.app_context():
db.create_all()
db.drop_all() # 同样必须在上下文里,实测上下文外调用报上面那句 RuntimeError -
实测建出来的表清单跟着模型走:
['long_name_model', 'user_profile', 'users']。 -
SQLALCHEMY_TRACK_MODIFICATIONS默认就是None(不追踪),显式设False只是把话说明白;设True会给每个对象记一份变更快照,白耗内存。 -
老笔记里的
SQLALCHEMY_COMMIT_ON_TEARDOWN已经彻底失效(FSA 2.0 就删了,键留着没人读)。实测:1
2
3同一会话里 add 不 commit -> 查得到 ['没提交']
新上下文里再查 -> []
正常 commit 后新上下文查 -> ['提交了']第一行看得到是因为同一会话有身份映射(identity map),并不是已经落库,
rollback()之后它就消失。结论:想提交就自己db.session.commit()。
数据的CURD操作
-
增删改都在
db.session上,改完必须commit:app.py 1
2
3
4
5
6
7
def insert():
fei = User(username='fei', email='fei@163.com')
ouya = User(username='ouya', email='ouya@163.com', age=31)
db.session.add_all([fei, ouya])
db.session.commit()
return '数据已插入' -
按主键查:老笔记的
User.query.get(2)还能用,但实测会发LegacyAPIWarning——SQLAlchemy 2.x 起Query.get()属于遗留 API,新写法是db.session.get():1
2session.get(User, 1) -> 'qiqi' age=20(default 生效)
User.query.get(2) -> 'fei',警告 1 条:LegacyAPIWarning -
改:拿到对象后直接改属性再
commit,实测age从 20 改成 33 生效。老笔记说「add带 ID 的对象会自动识别成更新」,其实从上下文里get出来的对象本来就在这个会话的脏集合里,add是多余的。 -
删:
db.session.delete(obj)再commit,实测删一条后 count 从 3 变 2。 -
回滚:
db.session.rollback()丢掉未提交的改动,实测['qiqi','fei','tmp']回滚后变['qiqi','fei']。 -
项目里常用的是逻辑删除:加一个
is_deleted布尔列,删除只改这一列,查询统一带filter_by(is_deleted=False)。
模型设计参考
字段类型
-
老笔记的类型表在本机逐个核对过都对得上,只有
BigInteger的 Python 类型要按 3.x 改成int(早就没有long了):类型 Python 类型 说明 Integerint32 位整数 SmallIntegerint16 位 BigIntegerint大整数 Floatfloat浮点 Stringstr变长字符串,要给长度 Textstr长文本 Booleanbool布尔 Datedatetime.date日期 Timedatetime.time时刻 DateTimedatetime.datetime日期时间 Intervaldatetime.timedelta时间间隔 -
db.TEXT这种大写别名实测还在(hasattr(db, 'TEXT')为 True),但 SQLAlchemy 2.x 的写法是小写类名。
字段选项
| 选项 | 默认值 | 说明 |
|---|---|---|
primary_key |
False |
主键,FSA 要求每个模型至少一个,习惯叫 id |
unique |
False |
唯一索引 |
index |
False |
普通索引 |
nullable |
True |
能否为空 |
default |
无 | Python 侧默认值,插入时才生效 |
server_default |
无 | 建表时写进 DDL 的默认值 |
- 实测三列的取值:
age是nullable=True default=ScalarElementColumnDefault(20);active设了nullable=False, server_default='1'之后default仍是None(默认值交给数据库);note两者皆空。 - 不写
__tablename__时表名由类名转换,实测UserProfile -> user_profile、LongNameModel -> long_name_model。
数据库的迁移
-
drop_all()+create_all()会把数据一起清掉,改表结构必须用迁移:Flask-Migrate(底层是 Alembic)对比模型和库的差异,生成脚本再执行,数据不丢。 -
装与接:
1
pip install flask-migrate
app.py 1
2
3
4from flask_migrate import Migrate
db = SQLAlchemy(app)
Migrate(app, db) -
老笔记的
MigrateCommand和manager.add_command('db', MigrateCommand)已经不存在了(那是 flask-script 时代的东西)。FSA 3.x + Flask-Migrate 4.1.0 只要Migrate(app, db),命令自动挂到flask db下面。 -
三步走,实测本机 Flask-Migrate 4.1.0 的子命令齐全(
init / migrate / upgrade / downgrade / revision / history / current / check / merge / stamp / show / edit / heads / branches / list-templates):1
2
3flask db init
flask db migrate -m "first"
flask db upgrade实测输出:
1
2
3
4db init -> rc=0,提示去编辑 migrations/alembic.ini 与 env.py
db migrate -> Generating ...\migrations\versions\43612e1d6ea3_first.py ... done
db upgrade -> rc=0
migrations 目录 -> ['README', 'alembic.ini', 'env.py', 'script.py.mako', 'versions'] -
init只跑一次(建migrations/目录,这个目录要进版本库),之后每次改模型都是migrate+upgrade。 -
自动对比不是万能的:改列名会被识别成「删一列 + 加一列」,数据就丢了;约束、索引、服务器默认值也不一定抓得到。所以
migrate生成的脚本要先打开看一眼再upgrade——实测脚本就落在versions/下,upgrade之前改它完全可行。 -
生产库上跑之前先备份;
flask db downgrade只能回退脚本里写了downgrade()的部分。