标签归档:开源

和捕蛇者说聊聊 Flask 2.0

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

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

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

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

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

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

超链接跳转费

昨天有人给《Flask 入门教程》书稿源码提交了一个 PR,主要的修改是在书中的链接前后添加了空格。比如:

  • 首先要注册一个 GitHub 账户,点击访问注册页面根据指示完成注册流程。登录备用。

改成了:

  • 首先要注册一个 GitHub 账户,点击访问 注册页面根据指示完成注册流程。登录备用。

我一直对这个排版风格持观望态度。如果合并的话,那就要在以后的书稿更新甚至所有网络写作中保持这个习惯,再三考虑之下,我还是决定暂不这样做。最主要的考虑是添加空格会影响阅读体验,好像本来平淡无奇的超链接突然自带聚光灯。一来在观感上突兀,二来会影响阅读的流畅感(大多数情况下链接文字本身也是句子的一部分)。

不过话说回来,超链接也该被拎出来亮一亮了,因为超链接在国内的网络环境里一直处于被打压和控制的状态:微信公众号不允许插入超链接,新浪微博从下个月起要停止把 URL 解析成超链接(只为白名单内的政府、公司等网站提供链接渲染服务),而知乎也曾悄悄停止把用户主页一句话介绍里的 URL 解析成超链接。在网络世界里,超链接是再平常不过的东西。但这些公司却把互联网的基础设施垄断、控制起来进行牟利、打压竞争对手以及用来把用户尽可能的圈在平台内。

我在想,新浪微博之类的平台在以后也许可以尝试收超链接费或是超链接跳转费(比如推出一个超链接套餐,100 块钱可以发 50 个链接),然后再按照点击量收取超链接点击费或是超链接流量费。听起来就像是政府要征收空气税和重力税……

除了不被渲染为超链接,有时在手机上访问超链接也要跨过千难万险。如果你在微信上打开一个超链接,你首先要跟 GFW 打声招呼,接着或许还会被网络运营商搜身,最后才会经过微信的审查。如果微信发现你要打开的是淘宝之类竞争对手的网址,或是它「自己认为」危险的不适合访问的网址,你就只能通过长按复制网址的方式用浏览器打开。如果你很不幸安装的是国产浏览器的话,那恭喜你还要再面临一层国产浏览器厂商的审查。

想让你的网站被渲染成超链接并且可以被正常访问?好,那就申报,登记,填表,备案吧。

也许未来会有很多人忘记为什么网页上一段文字里某些文字会是蓝色和下划线样式。

比修 Typo 还简单的开源贡献方式

最近给 WTForms 提交了一个 PR,这个 PR 向源码、测试和本地化文件里添加了 537 个句号。听起来似乎很奇怪,为什么 WTForms 会需要增加 537 个句号?别着急,下面会慢慢解释(事实上我只完成了一部分的工作,还有大概 500 个句号需要添加)。我发现我似乎很喜欢提交这种 PR,这类开源贡献没有太多技术含量(基本就是体力活),但是能有效提高项目的整体完美度,让用户获得更一致和舒服的体验。下面是一些可以归到这一类开源贡献的 PR。

1. 给 WTForms 添加 537 个句号

https://github.com/wtforms/wtforms/pull/620

WTForms 从添加 CSRF 保护功能作为分界,之前定义的验证错误消息都包含结尾的句号,之后的错误消息都漏掉了句号。这会导致错误消息不一致(想象同一个表单显示两个输入框的错误消息,一个有句号,一个没有句号)。这个 PR 补齐了源码、测试、本地化文本(POT 和部分 PO 文件)中错误消息的句号,包括 506 个英文句号和 31 个中文句号。

本地化文件在翻译时大都按照源文本决定是否添加句号,所以也存在错误消息不一致的问题。因为精力有限,在 32 个本地化文件里,我只更新了简体中文、繁体中文、日文、德文和俄文。大概还有二十几个本地化文件需要进行确认和更新,如果感兴趣的话,你可以考虑去做这件事。

2. 给 Flask 添加 96 个美元符号

https://github.com/pallets/flask/pull/2877

Flask 文档、和各类 README.md 文件里对于命令行命令的标识很混乱,有时没有命令提示符,有时用「>」,有时用「$」,有时用「#」。这个 PR 统一了所有命令行命令,统一添加美元符号作为提示符,仅在需要明确区分 Windows 命令的几处使用「>」。

3. 给 Flask 更换 13 个 URL

https://github.com/pallets/flask/pull/3427

Flask 去年陆续把文档迁移到了 palletsprojects.com 域名下, 访问旧的 pocoo.org 会进行跳转,这个 PR 更新了所有文档和源码里的旧 URL。

4. 给 PyCon ChinaFlaskCon 压缩 119 张图片

除此之外,勉强能沾上边的还有给 PyCon ChinaFlaskCon 的网站分别压缩了 105 和 14 张图片。因为缺乏规范,有些技术大会的网站图片在上传之前没有经过压缩和裁剪,这会让页面加载变得非常慢。这两个 PR(PyConChina #3FlaskCon #7)分别让两个网站的图片总大小从 25M 和 4M 降低到 5M 和 967KB。

给文档修 typo 是很常见的开源贡献类型,这也是很多人一开始参与开源的方式。有人甚至会走火入魔最后变成专业的「开源 typo 修复专家」,不停的用英文语法检查工具去检查每一个流行的开源项目文档……相比之下,上面这一类 PR 要比修 typo 更简单(在智力上),有时也更有价值。

我发现相对于技术实现,我其实更关注 API 设计和用户体验,总想要尽可能的追求设计的一致和美观。这也导致我会在写作和编程时花费大量时间在命名、文件组织、措辞、章节安排、排版、文案和彩蛋这些事情上。这大概就是我编程水平进步缓慢、写作速度缓慢的原因。

P.S. 文中的数字都是估算,大概会有 1~5 左右的偏差。精确的数字是为了让措辞看起来更一致和美观瞎编的。

COSCon 2019:一个野生程序员的开源故事

这是在 COSCon(中国开源年会)2019 上海 11 月 2 号分会场 1(开源社区与项目) 下午 2:20 开始的演讲《一个野生程序员的开源故事》的介绍和相关信息。

和标题透露的信息一样,这不是一个严肃的演讲(虽然 COSCon 看起来是一个很严肃的大会)。这是今年的最后一个演讲,明年不会弄那么多了,太累了……

购票和日程:https://www.bagevent.com/event/5744455

标题

一个野生程序员的开源故事

介绍

介绍其实可以忽略,因为根据前几次的演讲经验,演讲内容通常都会和简介有很多出入(跑题)。下面是简介:

2016 年,李辉开始学习 Flask。两年后,他加入了 Flask 开发团队。这中间发生了什么?其中大量的开源贡献起到了什么样的作用?参与开源对编程能力提高、个人品牌建设甚至是求职有哪些帮助?在本议题中,这些问题将会一一得到解答,你还会了解到如何踏出开源贡献的第一步,并且学到一些小技巧,比如参与开源涉及的英语和 Git 问题。

面向的听众:编程初学者,编程爱好者,程序员等想要参与开源的人。

总结

待补充

写作一本技术书,能给一个社区带来哪些改变?

写作《Flask Web开发实战》花费了一年多的时间,在这期间,除了编写5个项目实例和写作外,我还花了一部分时间来和书中涉及的Python库(主要是Flask扩展)打交道。这篇文章总结了这本书的写作给整个Flask社区带来的一些改变。

国内第一本Flask书

虽然国内已经有几本书介绍过Flask,但都是顺便介绍,而不是真正意义上的Flask书。因此,这本书可以说是国内第一本Flask书,很高兴能为国内的Flask社区带来这样一本书。希望这本书能够推动更多人了解和使用Flask,进而为社区贡献更多的力量。

完善多个开源项目

在实际介绍和使用某个库时,总会遇到各种各样的问题,主要有两类:

  • Bug
  • 不完善的用法或实现

Bug不用多说,肯定要处理。对于不完善的用法和实现,如果沿用原来的代码,一来不容易读者理解,二来还需要在书中加进很多不必要的内容。所以,我更倾向于让这些代码变得更好一点。

如果把不完善的实现写到书里,我会觉得非常不舒服。比如说,WTForms本身是支持设置内置的错误消息的语言的,我们可以设为中文,而不用手动写错误消息。但是在Flask-WTF中,因为内部重写了相关方法,导致没法在不使用Flask-Babel的情况下使用内置的翻译。问题来了:如果在第4章介绍Flask-Babel和i18n等相关概念的话,这显然需要占据大量篇幅,并不合适,而且这部分内容已经计划加入到第10章。

为此,书的安排没法改动,那么只好调整Flask-WTF的内部实现,所以就有了这个PR。类似的情况还有很多,比如Firefox支持headless模式后,Selenium中却没有提供和Chrome相同的导入接口;Flask-OAuthlib中,传入access令牌只能使用元组或字典类型,而不能使用更直观的字符串变量传入……

下面是一些写作期间提交的开源贡献:

当然,如果加上其他没有太大意义的文档更新,这个列表还可以更长。
 
值得特别说明的是Werkzeug的这个PR,这个PR对应的bug困扰了我很长一段时间。一开始我把问题归咎到python-dotenv身上,还创建了一个PR(#101),但是维护者迟迟没有回复。后来再次研究,发现可以直接在Werkzeug内部解决,于是创建了#1320,然后被lepture用更好的实现取代了(#1321)。不过,在python-dotenv创建的那个PR倒是促成了Pipenv的这个PR(#2386)。

推动发布新的版本

除了让PR被合并,还要让这些项目发布新的release,这样才能在项目源码公开后,让读者可以正常使用。在我的推动下,Flask-OAuthlib、Flask-Whooshee和Flask-Moment都发布了新的版本。

其他的项目,除了Werkzeug以外,大部分都在整个写作的时间跨度发布了新的版本。尤其重要的是Flask的1.0版本。从书一开始写作,我就直接采用了主分支的代码,书中我直接将版本号写为0.13。如果Flask迟迟不发布新版本,那我会陷入一个很尴尬的境地:要么大胆采用主分支代码,但是可能会出现变动,导致书中的内容不可靠;要么采用旧版本,那书出版后可能会很快面临过时的危险。还好,在写作接近尾声的4月末,新版本1.0发布了。

4个Flask扩展

用于集成Bootstrap的扩展Flask-Bootstrap目前的维护状态很糟糕:上一次release是17年1月,上一次合并commit是17年3月,而且已经很长时间不再处理PR和Issue。

原项目还存在很多问题:Jinja语法不标准、内置基模板引入不必要的复杂度、分页宏不支持传入URL片段值。除此之外,让我决定写新的扩展替代它的最主要原因是因为它不支持Bootstrap 4,而我不能接受在书中引入一个这样过时的项目。

为了解决这些问题,只好写了Bootstrap-Flask。最终决定写替代扩展的时候,书已经完成了三分之二,大量旧的内容和源码都要改写。把书稿和源码从Flask-Bootstrap和Bootstrap3迁移到Bootstrap-Flask和Bootstrap4是一个非常痛苦的过程,到现在还记忆犹新……

对于某些空白的领域,我写了三个扩展来简化集成操作:

5个Flask开源项目

在此之前,完善的Flask开源项目屈指可数,除了Flask官方提供的两个示例程序外,就只有Miguel Grinberg的两个程序。而这本书带来了5个相对比较完善、所有依赖都基于最新版本的开源项目(严格来说,第1个程序比较简单,可以排除在外):

我加入了Pallets Projects开发团队

今天早晨起来检查收件箱,收到了David Lord(Flask核心维护者)的邮件,他同意了我的申请——前段时间邀请他为我的新书《Flask Web开发实战》写推荐语,同时申请加入Pallets Projects开发团队(Pallets Team)。

Pallets Projects是什么?

简单来说,Pallets Projects就是“Flask项目集合”,为了更好的管理Flask相关项目而由Pocoo分化而来。它同时也是一个GitHub Organization,包括了所有Flask相关的项目,比如Flask、Werkzeug、Jinja、Click等等。

这意味着什么?

这意味着我对于Flask项目拥有更多的操作权限,可以更好的向Flask贡献代码,并且可以帮助处理Issue和Pull Request。