分类目录归档:Programming

和中学生们聊聊学习和使用 Python 的趣事

  • 录像:bilibili | YouTube
  • 嘉宾:王俊杰 / 胡博文 / Andy Zhou / Rice Zong
  • 主持人:李辉
  • 详情页:https://cn.pycon.org/2021/talks/young-pythonistas
  • 介绍:高中生和初中生们是怎么学习 Python 的?他们都开发了什么项目?他们未来会计划做程序员吗? 在这场圆桌里,一个高中生和三个初中生会一起聊一聊他们学习和使用 Python 的经历,以及他们的未来畅想。

这是 PyCon China 2021 第一天的一场圆桌讨论(PyHouse)。辛庆老师跟我说的时候,本来没打算参加,后来想到可以邀请我的两个小读者来聊聊,所以在前一天决定来策划和主持这场圆桌。

邀请的两个人一个是 Andy Zhou,他在六年级就开始学习 Python 了,初中时通过读我的书学习了 Flask,然后做了一个班级网站(博客程序 Flog),让同学们可以注册在上面写东西。另一个是陈绍坤(现在才想起来他似乎还在上六年级),知道他是因为他在一个知乎回答里介绍了自己学习编程的经历,而且提到有读我的书(文章?)。不过因为我在大会前一天才发出邮件,陈绍坤没来得及看到,看到邮件时圆桌讨论已经接近尾声……

第二天上午,Andy 的同学 Rice Zong 突然发邮件给我,做了一番相当正式的自我介绍,然后说想和我做朋友,原话是「我正式向你发出交朋友的邀请。希望你能接受这个朋友。」。哈哈,感觉好可爱(希望这样说他不会觉得冒犯)。他告诉我 Andy 跟他嘚瑟我发出去的圆桌邀请邮件,所以问我「作为初中生,如何才能参加 PyCon China 2022?就像 Andy 一样。」。看到最后这个问题,还没看清他说的是 2022,我就赶紧补了一封邀请邮件给他,这样我们就有了一位新嘉宾。再加上辛老师邀请的两位在上海现场的王俊杰和胡博文同学,四人成行。

我一开始准备了很多问题,但是几个人三下五除二就回答完了,而这时圆桌还剩一个小时。后面我已经不知道要说什么了,好在 Andy 和 Rice 实在是能聊,他们完全撑起了整场圆桌。再后来他们久仰大名的 Frost Ming 神秘现身;shell 叔给我们科普了很多法律相关的事情;现场的其他老师也加入进来聊起了网络安全……最后我实在坐不住了,只好把已经跑到月球的话题拉回来,给这场圆桌收了尾。这些跑题内容在最终视频里都剪掉了,要不然视频足足有两小时那么长。

也许是我笑点太低,不过和他们聊天真的非常开心,你很难不被他们的单纯和热情感染。希望明年可以看到他们几个来 PyCon China 演讲,期待明年的 PyCon China。

P.S. 这个视频是基于直播录屏的私人剪辑版本。视频中使用了冒险岛(MapleStory)的背景音乐 101 Building,我知道这样使用属于侵权,但我还是用了……版权属于 Nexon 公司。希望这是我最后一次未经授权使用版权音乐。

2021 年 Flask 用户调查报告

七月份创建了一个 Flask 用户调查问卷,到目前为止一共收集到 104 份提交,感谢各位的参与!这篇文章会对问卷收集结果做一个总结,作为一份(非官方的)2021 年(104 位中国)Flask 用户调查报告。

如果你想自己看原始数据,下面是剔除了隐私信息的问卷提交数据文件(CSV 格式):

https://helloflask.com/downloads/flask_report_2021.csv

如果你现在还想参与的话,完全来得及,下面是问卷的地址:

https://jinshuju.net/f/UY6Rd8

你在工作中使用 Flask 吗?

在提交的 104 份问卷里,接近一半的人在工作中使用 Flask,详情如下:

你在工作中使用 Flask 吗?

算上我,还没找到工作的人竟然只有 5 个(《震惊!某份民间调查显示 Flask 用户无业率仅有 4.8 %!》:P)。

Flask 中文文档标语翻译

前段时间发起了 Flask 中文文档翻译,目前正在龟速进行中,欢迎英语比较好的同学参与(翻译或审核已经提交的 PR)。文档首页的 logo 图片里有一句标语——「web development, one drop at a time」,我临时翻译为「Web 开发,一次一滴」。在 GitHub 仓库的讨论里,大家给出了更多更好的备选项。根据这次问卷投票的结果,「Web 开发,起于点滴」排在第一位(由 HelloFlask QQ 群里一位翻译专业的同学翻译),详情如下:

Flask 标语翻译

更保险的选择是「不作翻译」,在投票中排在第二位,最终我会考虑从这两者之间选择。另外,如果翻译的话,如果翻译的话,「Web」会考虑按照英文近年的惯用趋势而使用全小写(你觉得呢?​)。

P.S. 在 GitHub 上的投票结果里,@abersheeran 翻译的「Web 开发,起自微毫」和「任取随用的 Web 框架」票数最高。

对 Flask 的新功能请求 & 改进建议

剩下几个问题不方便详细统计和展示,我粗略看了一遍,整理出了关注度最高的几件事。我一一在下面评注了我的想法以及相应的动态。

添加更多 Web API 开发支持

开发接口时自动生成swagger

对 Web API 很友好的支持

加入pydantic用于类型检查

Flask 作为一个通用型框架,不会添加太多关于 Web API 这种细分方向的支持。除了手动集成这些功能/工具,你可以考虑选择基于 Flask 而且集成了这些功能的二次框架,比如 APIFlask、flask-smorest、Spectree 等。

添加基于 ASGI 的异步实现

加强对异步的支持

异步支持的不是很成熟

可能是速度吧,据说现在很多新框架都比Flask快,要淘汰Flask云云

Flask 目前的异步支持已经能够满足大部分使用场景。据我所知,基于 ASGI 的异步支持短期内不会实现。

而对于鼓吹性能的文章可以不用太在意:异步和高性能不直接划等号。技术选型不会只考量性能。benchmark 未必客观和能够反映真实情况。如果对异步有强需求,可以考虑用和 Flask 相同 API 的 Quart(一个 Flask 的 ASGI 异步实现),或是换用其他异步框架。

官方维护的扩展列表

一个针对新手的 flask extension 的指南

由Pallets Projects开发团队的成员或者flask官方统一所有第三方插件的开发与发布,目前太乱了,有些都快停更十年了,还占用名字。

各种插件扩展选择太多,但是又质量层次不齐,此外很多个人维护的扩展可能由于开发者精力有限在后期会出现项目生命周期的问题,如:flask_restful,需要官方对常用扩展维护一套比较简洁的扩展。当然这样的话可能又走上了Django的老路,可能作者正在计划的“Flask扩展收容计划”是一个不错的选择,起码可以管理起来。但是脱离原作者维护的项目后期发展如何又成为另一个话题。比如需要对插件进行遴选,另外需要对该计划由官方进行宣传等

这件事我之前有计划在做,前段时间注册了 flaskextensions.org,想用来做一个这样的扩展推荐列表。在 Pallets 会议上沟通之后,决定交给 Pallets 官方来做,所以把域名转给了 Pallets 团队,后续会做一个这样的列表出来:列出来推荐的 Flask 扩展,并给出失去维护扩展的替代品。

另外 Pallets 在 GitHub 创建了一个 pallets-eco 组织,用来收纳失去维护(维护者不想再继续维护)的流行 Flask 扩展,让它们保持健康的维护状态(由社区维护)。目前有两个扩展进入这个组织,分别是 Flask-Caching 和 Flask-OpenID。

脚手架工具和大型项目组织

统一并明确开发的工程化流程,包括项目应该新建那些文件夹等。

缺少小白懒人快速一键生成集成框架(webadmin, mysql)

引入蓝图想搞玩大型项目,可大型项目又需要自己组织好项目结构,需要一个对flask很熟悉的人做这事 还不如用django。官方推一个脚手架生成项目模板吧像vue-cli一样 包括是否使用orm等插件,不然还不如django搭建起来快。。

作为一个微框架,Flask 的初衷是不限定项目文件组织形式,所以官方不太可能会出一个脚手架工具或是项目组织指南。在工厂函数和蓝本这两个概念的基础上,你可以自由组织你的项目。另一方面,市面上已经有很多项目模板或是脚手架工具(比如 cookiecutter-flask),也有很多介绍 Flask 项目组织的文章,你可以根据这些工具和文章制定自己的规则,然后为你的组织或团队确定一个项目组织规范或是写一个脚手架工具,或许这才是 Flask 的「正确食用方式」。如果你更需要一个固定的项目组织模式,那么 Django 或许是更好的选择。

我也有计划写一个更简单的脚手架工具(对我来说市面上那些都太复杂,引入了太多扩展和工具),同时给出一份 Flask 项目组织建议,这件事也许会在写《Flask Web 开发实战》第二版的过程里完成。

Bootstrap-Flask 的 Bootstrap 5 支持

Bootstrap-Flask 希望可以早点同步 Bootstrap5 的相关内容。因为Bootswatch的最新版本有我想要使用的组件,但是Bootstrap-Flask只支持到Bootstrap4,所以有些宏无法正常显示,比如render_form等。还有希望Bootstrap-Flask的wiki能够更加的完善和细节,我会持续关注,大佬辛苦

提交的问卷里有一条说到这件事,此前在 Twitter 和 GitHub 上也有人提到,所以也放到一起说一下。我已经在做这件事了,基本的 Bootstrap 5 支持已在 #161 完成,完整的实现会在下个月完成(详见 #162),届时会随 2.0 版本发布。

除了这些,提交的问卷里还有很多其他的建议和问题,我没法一一回应。有时间我会看看问题里提出的问题有哪些我可以试着解决和改善。同时也欢迎你一起尝试解决这些提出的问题,感兴趣的话,去翻翻上面给出的问卷数据吧。

总结

总体来看,Flask 社区在朝着好的方向发展,希望明年这里提到的大多数计划都会有着落。一起加油!

P.S. FlaskCon 2021 会在今年 12 月举办,如果你有 Flask 相关的内容想分享,欢迎报名(英文,预录制演讲)。


相关链接:

欢迎填写 Flask 用户调查问卷

以参加捕蛇者说播客录制 Ep 30 为契机,创建了一个 Flask 用户调查问卷,用来收集 Flask 用户的反馈和建议。尽管这个问卷是由我个人而不是 Flask 官方(Pallets)发起(不过 Flask 官方也在计划着做一个调查问卷),但是我会把收集到的信息反馈到 Flask 开发团队进行讨论。因此,你的建议的确有可能让 Flask 变得更好。

不管你对于 Flask 是有明确的变动建议,还是只是对某个功能不甚满意,都可以把你的想法写下来。谢谢!

问卷地址:https://jinshuju.net/f/UY6Rd8


同时借这个问卷送出四本《Flask Web 开发实战》,填写问卷即可参与。每份问卷会有一个提交序号,中奖序号为 27、36、41、58。预计抽奖会在 7 月 22 号完成,届时抽奖结果会更新到这篇文章。

7 月 21 日更新,抽奖结果已产生:

blank

和捕蛇者说聊聊 Flask 2.0

六月初,应 laike9m 邀请做客捕蛇者说录了一期播客。今天中午发布了上半部分:Ep 30. 和李辉聊聊 Flask 2.0,关于自由职业的下半部分正在剪辑中,预计八月初发布。

这是我第一次录播客。录制那一天,房间里还没有装空调,而开风扇会导致风声录进去,我只能用静静降温法;为了防止录进邻居打骂孩子的声音,我又把门窗闭紧,所以录到临近中午,感觉越来越热。一开始还有点紧张和兴奋,但是我从来没有和别人聊过两小时那么久,录到后面,我就像漏气的气球一样,慢慢瘪了下去。

七月初拿到剪好的第一期,觉得可以再优化一下,所以就自告奋勇再剪一遍。花了接近十个小时,剪掉了很多「呃」、「嗯」、「对」、「然后」、「所以」……在这个过程里也发现不少自己说话上的毛病。

这一期上半部分聊了我从学习 Flask 到成为维护者的经历,这些在 19 年的 COSCUP 演讲简单介绍过。下半部分关于自由职业本来有不少内容想聊,但是因为说太多话有点累,所以有一些漏掉的话题就没有再提出来。录完的这些天有时会突然想到一些很有趣但忘记说的事情,偶尔还会想要不要再约着录一个补丁,也计划着写文章作补充。另外这一期虽然聊到了 FastAPI,但我对它了解并不多,如果有机会的话,以后还想再录一期详细聊聊 FastAPI 和 APIFlask,或是再聊一聊技术写作、翻译和演讲。

最后,如果你用过 Flask,欢迎来填写这个 Flask 用户调查问卷。关于捕蛇者说播客的更多信息,可以访问它的主页和 Twitter 了解。

下期:和捕蛇者说聊聊自由职业

PyCon US 2021: FastAPI Seems Good, so Why Don’t We Build Something Similar For Flask?

Meta:

这是我第一次参加 PyCon US,也是第一次做英文演讲。也许会有一些语法和发音的问题,不过因为时间有限,我已经尽力了……这次开始准备的比较晚,演讲基本是在三天内完成的,演讲前一天花了一整天时间准备,从早上一直到第二天两点。总耗时 18 小时 41 分钟。相比之下,同样是五分钟的闪电演讲,在 PyCon China 2019 上海场的闪电演讲《Python 虚拟环境和依赖管理工具大乱斗》却花费了接近 40 个小时(大部分时间都用来做幻灯片了)。

这个演讲本来是一个比较深入的主题演讲,不过因为主题演讲申请惨遭淘汰,只好换成闪电演讲。演讲灵感来自前段时间的那篇《请不要把 Flask 和 FastAPI 放到一起比较》。

尽管是预录制演讲,但是不知道主办方哪里没弄好,实际大会直播的时候音画不同步,卡顿很严重(见官方发布的演讲视频)。

开始翻译 Flask 文档

我在上周开始策划 Flask 文档翻译的事,制定了大致的翻译流程,创建了翻译协调仓库和翻译模板仓库。中文翻译作为这个流程的试水项目,在上周末正式(静悄悄)启动。

blank

启动中文翻译项目的第一步是把 logo 里的标语「web development, one drop at a time」翻译成中文,这让我想起来一个也许冷也许不冷的冷知识。很多人知道 Flask 的名字是对 Bottle 的双关语——另一个容器/另一个 Python Web 框架。那为什么 Python Web 框架爱用容器做名字?其实是因为这些 Python Web 框架都是基于 WSGI 规范实现的,而 WSGI 不知从哪天起流行被读作 Whiskey(威士忌),所以这两个 Python Web 框架才叫做 Bottle 和 Flask,所以才有「Web 开发,一次一滴」。

欢迎在这些 discussions 中分别投票选出最佳翻译词汇、中文 logo 字体和中文标语。

回到正题。如果你对 Flask 足够熟悉,并且擅长翻译,欢迎参与进来!翻译通过 GitHub 进行协作(greyli/flask-docs-zh)。除了翻译文档,我们也需要有丰富翻译经验的朋友来审阅提交的翻译,欢迎在 GitHub 上关注(点 Watch 按钮)这个项目以接收新增翻译提醒。

下面是参与翻译之前要了解的三件事:

  1. 请务必完整阅读 Contributing Guide 了解翻译流程,然后阅读这个 issue 了解翻译要求。
  2. 需要强调的是,完成一章的翻译要提交两个 PR:第一个 PR 在 README 中对应的章节条目后添加自己的用户名以认领章节;第二个 PR 翻译对应的 .po 文件并勾选完成的章节条目。先认领,再翻译,一次只认领一章。
  3. 不要改动任何 ReStructuredText 标记、变量/类/函数/方法名称、URL 等。

如果有其他问题和相关想法,请创建 discussion 发起讨论;如果对翻译流程和项目设置有改进建议,或是发现了翻译错误和笔误,请创建 issue 反馈。

这个项目在后期会转移到 FlaskCWG 组织,并在翻译完成后链接到 Flask 官方文档。

Flask 2.0 版本发布

Flask 以及 Flask 依赖的 5 个 Pallets 项目都在今天发布了新的主版本(下面的链接指向各个项目的主版本变动日志):

​你可以使用下面的命令更新 Flask:

 pip install -U flask

如果你使用的国内 PyPI 镜像还没有同步最新版本,可以通过下面的命令临时切换到官方 PyPI 源:

 pip install -U flask -i https://pypi.org/simple/

这篇文章会介绍一些 Flask 新增的特性,完整的变动可以参考上面各个项目的变动日志。

三个核心特性

嵌套蓝本(#3923)

对于一个比较大的项目,一般会使用蓝本来组织不同的模块。而如果你的项目非常大,那么嵌套蓝本就可以派上用场了。借助嵌套蓝本支持,你可以在某个蓝本之上再创建多个子蓝本,对项目进行多层模块化组织(而且支持无限嵌套,你可以嵌套很多层):

 parent = Blueprint("parent", __name__)  # 创建父蓝本
 child = Blueprint("child", __name__)  # 创建子蓝本
 parent.register_blueprint(child, url_prefix="/child")  # 把子蓝本注册到父蓝本上
 app.register_blueprint(parent, url_prefix="/parent")  # 把父蓝本注册到程序实例上

这样在生成子蓝本的 URL 时需要传入完整的端点链:

 url_for('parent.child.create')
 /parent/child/create

这个特性来源于一个 2012 年创建的 feature request issue。

基本的 async/await 支持(#3412)

Flask 2.0 带来了基本的异步支持,现在你可以定义异步视图(以及异步错误处理函数、异步请求钩子函数):

 import asyncio
 from flask import Flask
 ​
 app = Flask(__name__)
 ​
 @app.route('/')
 async def say_hello():
     await asyncio.sleep(1)
     return {'message': 'Hello!'}

注意要先安装额外依赖:

 pip install -U flask[async]

顺便说一句,如果你在 Windows 上使用 Python 3.8,那么会有一个来自 Python 或 asgiref 的 bug 导致出错:ValueError: set_wakeup_fd only works in main thread。可以通过下面两种方式(任选一种)处理(具体参考这个 SO 回答):

  • 升级到 Python 3.9
  • 在你的入口脚本顶部添加临时修复代码:
 # top of the file
 import sys, asyncio
 ​
 if sys.platform == "win32" and (3, 8, 0) <= sys.version_info < (3, 9, 0)::
     asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())

不过目前只是一个基于 asgiref 的异步实现,作为异步支持的第一步,后续还会进行更多的优化和改进,更多相关信息可以参考文档。

快捷路由装饰器(#3907)

新增了下面的快捷路由装饰器:

  • app.get()
  • app.post()
  • app.delete()
  • app.put()
  • app.patch()

举例来说,使用 app.post() 等同于 app.route(methods=['POST']):

 from flask import Flask
 ​
 app = Flask(__name__)
 ​
 @app.post('/')
 def index():
     return {'message': 'Hello!'}

注意不要在这些快捷装饰器里传入 methods 参数。如果需要在单个视图处理多个方法的请求,使用 app.route()。

我在某次 pallets 会议上提议添加这些装饰器时一开始是被拒绝的,后来 Phil Jones 创建了 #3907 经过二次讨论后才最终合并(被拒绝后我就把当时正在开发的 APIFlask 从扩展改成了继承 Flask 基类的框架,然后加了这些装饰器)。

我添加的三个特性

修复执行 flask run 找不到程序的奇怪设定(#3560)

这个像 bug 又像是 feature 的设定我在《一个困扰我两年的 Flask「Bug」》里详细说过,最终终于在两年后修复了。

支持在 .flaskenv 和 .env 文件里写中文(#3932)

我在《Flask Web 开发实战》第一章介绍 .flaskenv 文件时给了一个示例,演示如何添加注释:

SOME_VAR=1
# 这是注释

但这个示例没有实际测试……加了中文其实会报错,后来有两次收到读者反馈,最终终于在三年后修复了。

为文档添加命令切换面板(#3714)

这个或许算不上特性,不过在我看来是对用户非常友好的变动。除了个别不需要区分操作系统和命令行程序的命令外,我给文档里所有的命令添加了支持切换 Bash/CMD/Powershell 以及 macOS/Linux/Windows 的切换面板(面板的样式后续会有一些优化):

blank

其他的有用特性

  • 优化了浏览器缓存控制,对 CSS、图片等静态文件做出的变动会在程序重载后立刻更新,不再需要手动清除页面缓存。
  • Werkzeug 的 multipart 解析(尤其是大文件上传处理)性能提高了 15 倍。
  • 配置对象增加 Config.from_file() 方法支持从任意文件加载器导入配置(比如 toml.load、json.load),未来会取代 Config.from_json() 方法。
  • 在使用环境变量 FLASK_APP 指定工厂函数时支持传入关键字参数。
  • flask shell 支持 tab 和历史补全(需要安装 readline)。
  • CLI 系统优化了找不到程序时的错误处理和错误输出显示,同时修正了 Windows 上的命令行颜色输出。

破坏性变动

主要的破坏性变动(breaking change)是意外的把 send_from_directory() 函数的第二个参数名称直接由 filename 重命名为 path,将会在 2.0.1 加回来(#4019)。

另外 send_file() 函数的三个参数也进行了重命名(旧名称将在 2.1.0 移除):

  • attachment_filename -> download_name
  • cache_timeout -> max_age
  • add_etags -> etag

其他重要变化

  • 不再支持 Python 2 和 Python 3.5。
  • 所有 Pallets 项目都添加了 type hinting,这意味着更好的 IDE 自动补全体验。
  • 所有仓库的主分支由 master 改为 main。如果你在本地克隆了 Flask 等仓库,可以使用下面的命令来更新:
 git branch -m master main
 git fetch origin
 git branch -u origin/main main
 git remote set-head origin -a

感谢支持

这次更新对于整个 Pallets 项目来说是一个新的里程碑。接下来还有许多事情要做:FlaskCon 2021 正在准备中,新建立的 Flask 社区工作小组(Flask Community Work Group)正在进行 Flask 文档翻译(如果你对中文翻译感兴趣,可以订阅这个讨论)、被遗弃扩展收容计划(这是我一直想做的事情)等等。感谢支持,敬请期待!

欢迎通过下列途径关注 Pallets 项目:

相关文章:

APIFlask:一个基于 Flask 的 Web API 框架

经常看到有人把 FastAPI 和 Flask 放到一起比较,但是却没有意识到这完全是两种东西——前者是基于 Web 框架 Starlette 添加了 Web API 功能支持的(框架之上的)框架,而后者是和 Starlette 同类的通用 Web 框架。你怎么能让小明和骑电动车的小军赛跑然后还夸小军好快好强?为了让框架 PK 爱好者们有一个更公平的比较对象,从一份 APIFairy 0.6.2 版本的 fork 开始,我实现了一个基于 Flask 的 Web API 框架——APIFlask:

blank

APIFlask 在 Flask 的基础上添加了更多 Web API 相关的功能支持,核心特性包括:

  • 更多方便的装饰器,比如 @app.input()、@app.output()、@app.get()、@app.post() 等等
  • 自动反序列化和验证请求格式,当请求数据不符合模式类要求时,会自动生成包含错误详细信息的错误响应(基于 Webargs)
  • 自动格式化和序列化响应数据,在定义好响应模式后,你可以直接在视图函数返回一个模型类对象,或是返回字典(基于 Marshmallow)
  • 自动生成 OpenAPI Specification 文件,你可以把这个文件导入到 API 调试工具或是用来生成客户端代码(基于 APISpec)
  • 自动生成交互式 API 文档,并自动为蓝本和视图设置对应的标签分类(基于 Swagger UI and Redoc)
  • 自动为 HTTP 错误生成 JSON 格式的错误响应

下面是一个最基础的示例程序:

 from apiflask import APIFlask, Schema, abort
 from apiflask.fields import Integer, String
 from apiflask.validators import Length, OneOf
 ​
 app = APIFlask(__name__)  # 可以使用 title 和 version 参数来自定义 API 的名称和版本
 ​
 pets = [
     {
         'id': 0,
         'name': 'Kitty',
         'category': 'cat'
     },
     {
         'id': 1,
         'name': 'Coco',
         'category': 'dog'
     }
 ]
 ​
 # 定义一个请求数据模式类
 class PetInSchema(Schema):
     name = String(required=True, validate=Length(0, 10))  # 可以使用 description 参数添加字段描述
     category = String(required=True, validate=OneOf(['dog', 'cat']))
 ​
 # 定义一个响应数据模式类
 class PetOutSchema(Schema):
     id = Integer()
     name = String()
     category = String()
 ​
 ​
 @app.get('/pets/<int:pet_id>')
 @app.output(PetOutSchema)  # 使用 @output 装饰器标记响应数据模式
 def get_pet(pet_id):
     if pet_id > len(pets) - 1:
         abort(404)
     # 在真实程序里,你可以直接返回 ORM 模型类的实例,比如
     # return Pet.query.get(1)
     return pets[pet_id]
 ​
 ​
@app.patch('/pets/<int:pet_id>')
@app.input(PetInSchema(partial=True))  # 使用 @input 装饰器标记请求数据模式
@app.output(PetOutSchema)
def update_pet(pet_id, json_data):  # 通过验证后的请求数据字典会注入到视图函数,默认参数名为 json_data
    if pet_id > len(pets) - 1:
        abort(404)
    for attr, value in json_data.items():
        pets[pet_id][attr] = value
    return pets[pet_id]

P.S. 你也可以使用类视图(class-based views),具体示例见这里。

如果你想在你的电脑上运行这个示例,可以先用下面的命令安装 APIFlask(需要 Python 3.7 及以上版本,Flask 1.1 及以上版本):

Linux 和 macOS:

 $ pip3 install apiflask

Windows:

 > pip install apiflask

安装完成后把上面的代码保存到文件 app.py,然后执行下面的命令运行程序:

 $ flask run

现在你可以在浏览器访问 http://localhost:5000/docs 查看基于 Swagger UI 自动生成的交互式 API 文档:

Swagger UI

或者访问 http://localhost:5000/redoc 查看基于 Redoc 生成的 API 文档:

Redoc

访问 http://localhost:5000/openapi.json 可以获取自动生成的 OpenAPI spec 文件。

这个示例程序的完整版本可以在 https://github.com/greyli/apiflask/tree/master/examples 看到。如果你想了解更多用法,可以阅读文档中的基本用法一章(目前只有英文)。

APIFlask 只在 Flask 之上做了轻量级包装,所以你实际上仍然是在写一个 Flask 程序,所有 Flask 的特性都完全兼容。你只需要记住下面两处不同点:

  • 创建程序实例的时候使用 APIFlask 类(from apiflask import APIFlask)。
  • 创建蓝本实例的时候使用 APIBlueprint 类(from apiflask import APIBlueprint)。
  • 使用 apiflask.abort() 函数返回 JSON 格式的错误响应。

以下面的 Flask 程序为例:

 from flask import Flask, request, escape
 ​
 app = Flask(__name__)
 ​
 @app.route('/')
 def hello():
     name = request.args.get('name', 'Human')
     return f'Hello, {escape(name)}'

迁移到 APIFlask 只需要改动两行代码:

 from apiflask import APIFlask  # 第一行
 from flask import request, escape
 ​
 app = APIFlask(__name__)  # 第二行
 ​
 @app.route('/')
 def hello():
     name = request.args.get('name', 'Human')
     return f'Hello, {escape(name)}'

欢迎提出改进建议,报告 bug 或是分享其他任何相关的想法。你也可以在 GitHub 上创建 Issue,或是提交 PR 来改进它。谢谢!

PyCon China 2020: Python 技术名词发音指南

这是我在今年 PyCon China 的闪电演讲,不过没有去年那么闪电:

Django 怎么读?十个 Python 程序员也许会有十种读法。如果这个你刚好会读的话,那么还有 Werkzeug、SQLAlchemy、Gunicorn、PyPI、Bokeh、Huey…… 根据可靠来源,因为错误的发音,两个 Python 程序员在交谈时平均每小时会浪费三分钟时间用来互相确认和纠正名词发音。为了减少整个 Python 社区因为错误的技术名词发音产生更多的熵,这个演讲带来了一个可信度 95% 的 Python 技术名词发音指南。

这是我第一次做线上直播形式的演讲,在提交演讲申请之后我一直在想不知道会有多少人来听。也一直在担心 Windows 会不会蓝屏,国产软件会不会弹广告,猫会不会拔掉猫的电源……后来才知道可以提前录制,那就没什么好担心的了,所以你坐在屏幕前看到的我,当时也正坐在屏幕前看自己。

准备的过程中发现这可能是很容易带来争议的演讲:有些读音没有标准,有些读音我自己也读错好久,再加上有些人觉得发音无关紧要,有些人觉得错的人多了就成了正确发音,有些人还会守着错误发音扯到文化自信……不过没关系,反正这个演讲总能让台球再转起来一次,至少也可以短暂的让大家再一次正视错误发音问题。这个演讲也是我自己的一个发音纠正练习。

你也许觉得发音正不正确无关紧要,不,这其实是一件很重要的事情。拥有正确一致的发音可以让大家见面聊天更顺畅一点,不用停下来确认说的是同一个东西,在听播客和演讲的时候也不用被错误的发音打断思绪。而且有些错误的发音并不好听,比如「Windows 叉屁」……你只要稍稍花一点心力就可以避免让错误的发音变成主流发音,最后变成「事实上的正确发音」。一旦你不在乎这一点对错,生活里的很多事情都会慢慢变成无所谓和差不多另一方面,这份指南也希望可以给技术演讲和播客提供一个参考,如果 Python 培训班和各种九块九的网课感兴趣的话,这个指南或许可以放在第一课的最后作为延伸阅读的内容。只此两项,就可以避免错误发音大范围传播。

请从今天开始重视发音吧!


演讲准备备注:

  • 耗时:48h 35m(加上后期写这篇文章和上传视频的时间)
  • 幻灯片工具:Marpit
  • 一共录了 9 遍,演讲前一晚匆匆录了最后一版,很努力也才把时长压缩到 15 分钟(要求 10 分钟长度和最多五分钟偏差),有点赶。今天下午又重新录了一版,放轻松刚好 20 分钟。
  • 感觉线上演讲有点无聊……没有观众反馈,也没有紧张和兴奋的感觉。
  • 这个演讲最后本来有一个恶搞。虽然是录播,但我原本打算在最后假装有问答环节,问「大家有没有问题要问?」,然后停顿一分钟,再说「好,那没有问题就拜拜啦」。因为这样会让超时更加严重,而且会有点让人讨厌,所以最后就去掉了。现在的结尾的意思是「用 Python 之杖赐予各位听众 Pythonic 原力」。
  • PyCon China 网站也太难看了……

Flask 新书完成时间推迟

很抱歉没能按照预期时间完成 Flask 新书。本来这个消息要到四月一号(预估的完成时间)发布的,但是怕被当做愚人节玩笑,所以还是提前一点比较好。

去年大部分时间花在了组织活动和准备演讲上,而今年前几个月又大都用来玩游戏和做外包了,所以一直没有全身心投入到新书写作上,目前大约只完成了一半……

为新书写了一个简单的主页,地址在 http://helloflask.com/book/2。我在页面上放了一个写作进度条,方便感兴趣的人了解进度。同时也加了一个订阅功能,你可以用 Email 来订阅新书的发布消息。

感谢大家的关注和支持,祝大家一切顺利。

明天开始专心写作。