(给Python开发者加星标，提升Python技能)
编译：linux中国-geekpi，英文：Moshe Zadka
https://linux.cn/article-11624-1-rel.html
最好将文档作为开发过程的一部分。Sphinx 加上 Tox，让文档可以轻松书写，并且外观漂亮。
Python 代码可以在源码中包含文档。这种方式默认依靠 docstring，它以三引号格式定义。虽然文档的价值是很大的，但是没有充足的文档的代码还是很常见。让我们演练一个场景，了解出色的文档的强大功能。
经历了太多在白板技术面试上要求你实现斐波那契数列，你已经受够了。你回家用 Python 写了一个可重用的斐波那契计算器，使用浮点技巧来实现 O(1) 复杂度。
代码很简单：
# fib.pyimport math_SQRT_5 = math.sqrt(5)_PHI = (1 + _SQRT_5) / 2def approx_fib(n):    return round(_PHI**(n+1) / _SQRT_5)
(该斐波那契数列是四舍五入到最接近的整数的几何序列，这是我最喜欢的鲜为人知的数学事实之一。)
作为一个好人，你可以将代码开源，并将它放在 PyPI 上。setup.py 文件很简单：
import setuptoolssetuptools.setup(    name='fib',    version='2019.1.0',    description='Fibonacci',    py_modules=["fib"],)
但是，没有文档的代码是没有用的。因此，你可以向函数添加 docstring。我最喜欢的 docstring 样式之一是 “Google” 样式。标记很轻量，当它放在源代码中时很好。
def approx_fib(n):    """    Approximate Fibonacci sequence    Args:        n (int): The place in Fibonacci sequence to approximate    Returns:        float: The approximate value in Fibonacci sequence    """    # ...
但是函数的文档只是成功的一半。普通文档对于情境化代码用法很重要。在这种情况下，情景是恼人的技术面试。
有一种添加更多文档的方式，专业 Python 人的方式通常是在 docs/ 添加 rst 文件( reStructuredText 的缩写)。因此 docs/index.rst 文件最终看起来像这样：
Fibonacci=========Are you annoyed at tech interviewers asking you to implementthe Fibonacci sequence?Do you want to have some fun with them?A simple:code:`pip install fib`is all it takes to tell them to,um,fib off... automodule:: fib   :members:
我们完成了，对吧？我们已经将文本放在了文件中。人们应该会看的。
使 Python 文档更漂亮
为了使你的文档看起来更漂亮，你可以利用 Sphinx，它旨在制作漂亮的 Python 文档。这三个 Sphinx 扩展特别有用：
sphinx.ext.autodoc：从模块内部获取文档
sphinx.ext.napoleon：支持 Google 样式的 docstring
sphinx.ext.viewcode：将 ReStructured Text 源码与生成的文档打包在一起
为了告诉 Sphinx 该生成什么以及如何生成，我们在 docs/conf.py 中配置一个辅助文件：
extensions = [    'sphinx.ext.autodoc',    'sphinx.ext.napoleon',    'sphinx.ext.viewcode',]# 该入口点的名称，没有 .rst 扩展名。# 惯例该名称是 indexmaster_doc = "index"# 这些值全部用在生成的文档当中。# 通常，发布(release)与版本(version)是一样的，# 但是有时候我们会有带有 rc 标签的发布。project = "Fib"copyright = "2019, Moshe Zadka"author = "Moshe Zadka"version = release = "2019.1.0"
此文件使我们可以使用所需的所有元数据来发布代码，并注意扩展名(上面的注释说明了方式)。最后，要确保生成我们想要的文档，请使用 Tox 管理虚拟环境以确保我们顺利生成文档：
[tox]# 默认情况下，`.tox` 是该目录。# 将其放在非点文件中可以从# 文件管理器或浏览器的# 打开对话框中打开生成的文档，# 这些对话框有时会隐藏点文件。toxworkdir = {toxinidir}/build/tox[testenv:docs]# 从 `docs` 目录内运行 `sphinx`，# 以确保它不会拾取任何可能进入顶层目录下的# 虚拟环境或 `build/` 目录下的其他工件的杂散文件。changedir = docs# 唯一的依赖关系是 `sphinx`。# 如果我们使用的是单独打包的扩展程序，# 我们将在此处指定它们。# 更好的做法是指定特定版本的 sphinx。deps =    sphinx# 这是用于生成 HTML 的 `sphinx` 命令。# 在其他情况下，我们可能想生成 PDF 或电子书。commands =    sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html# 我们使用 Python 3.7。# Tox 有时会根据 testenv 的名称尝试自动检测它，# 但是 `docs` 没有给出有用的线索，因此我们必须明确它。basepython = python3.7
现在，无论何时运行 Tox，它都会为你的 Python 代码生成漂亮的文档。
在 Python 中写文档很好
作为 Python 开发人员，我们可以使用的工具链很棒。我们可以从 docstring 开始，添加 .rst 文件，然后添加 Sphinx 和 Tox 来为用户美化结果。
你对好的文档有何评价？你还有其他喜欢的方式么？请在评论中分享它们！
推荐阅读  点击标题可跳转
使用 Sphinx 制作简洁而又美观的文档
Windows 文件名非用反斜杠？Python 小技巧帮你解决这个麻烦
觉得本文对你有帮助？请分享给更多人
关注「Python开发者」加星标，提升Python技能
好文章，我在看❤️

Chrome采集内核代码说明文档




版本
备注
编写人
时间




V1.0
初稿
wangnn01
2020-1-8


文章目录
Chrome采集内核代码说明文档
一、使用说明
二、功能概述
1.功能框图
2.模块简介
2.1 WEB API
2.2 MySQL Connector/C++
2.3 Mojo消息管道
2.4 内核数据抽取模块
Jsoncpp
数据抽取
2.5 功能描述
三、程序代码
1.代码结构
（1）路径：src/content/browser
（2）路径：src/third_party/blink/renderer/core/html/parser
（3）路径：src/third_party
（4）路径：src/services
（5）路径：src/chrome/browser/ui/startup
（6）路径：src/chrome/installer/util
2.代码调用图

一、使用说明
Chrome采集内核基于的Chromium版本为80.0.3969.0，运行于Windows系统。

　Chrome采集内核最终使用方式是安装包。


​　双击后静默安装，安装路径为C:\Users\user name\AppData\Local\Chromium。


​　结合采集工具进行数据抽取：在采集工具中输入url，启动Chrome，加载网页的同时进行数据抽取，并返回结果给采集工具。
二、功能概述
1.功能框图


注：Chromium为Chrome的开发者版本
2.模块简介
2.1 WEB API
Web API 是Web 应用程序接口。包含了广泛的功能，Web 应用通过API接口，可以实现存储服务、消息服务、计算服务等能力。Web API是一种数据请求框架是基于HTTP协议的服务，能够直接返回用户的数据请求，可以根据请求报文来返回的相应数据格式。包括Json和XML。

　Chrome采集内核基于HTTP协议，将内核作为HTTP client端，采集工具作为HTTP server端，实现内核和采集工具之间的数据通信Web API 。在此，内核首先向采集工具发GET请求，采集工具发送响应为Json类型的Task字符串。在后续进行内核数据抽取生成Json类型的Result字符串之后，将其POST到采集工具进行后续处理。
2.2 MySQL Connector/C++
​　C++语言本身并没有提供访问数据库的东西，一般使用访问数据库的驱动。MySQL Connector/C++是C++连接数据库的引擎，起着C++和数据库之间桥梁的作用。
​　在Chrome采集内核中实现了MySQL Connector/C++，可以将Json类型的Result字符串写入MySQL数据库。后续会支持其他类型数据库的数据存储。
2.3 Mojo消息管道
​　Mojo是Chromium提供的用于进程间或进程内的模块间通信的一种机制，它屏蔽了通信时的类型转换。如需了解更多详细信息，请参考Chromium Mojo官方文档。
​　在Chrome采集内核中建立了两个消息管道，实现render进程和browser进程间的通信，详细创建和使用方法请参考另一篇文档[Chromium Mojo消息管道的创建和使用](./Chromium Mojo消息管道的创建和使用.md)：

　

　（1）带响应的Mojo消息管道（左侧蓝色条纹矩形）：render进程通过Mojo让browser进程执行GET请求获取到Json类型的Task字符串，然后将Task字符串作为响应返回至render进程。在render进程中，进行内核数据抽取生成Json类型的Result字符串之后，将Result字符串传输到browser进程并POST到采集工具进行后续处理。
​　（2）不带响应的Mojo消息管道（右侧蓝色条纹矩形）：用于将内核数据抽取生成Json类型的Result字符串从render进程传输到browser进程，然后利用MySQL Connector将其写入MySQL数据库。
2.4 内核数据抽取模块
该模块主要实现：
​　（1）解析Task Json；
​　（2）根据Task Json进行相应的数据抽取；
​　（3）生成Result Json；
​　其中，如何根据Task Json进行相应的数据抽取是重点。

　首先，简单介绍用于解析和生成Json的第三方库Jsoncpp。
Jsoncpp
​　详细信息请参考另一篇文档[C++ Json解析库Jsoncpp的下载+编译+使用](./C++ Json解析库Jsoncpp的下载+编译+使用.md)
数据抽取
接下来以流程图简单介绍如何根据Task Json进行相应的数据抽取。


2.5 功能描述
​　S1：在内核的browser进程中，采集内核（HTTP Client）向采集工具（HTTP Server）发送GET请求，接着采集工具（HTTP Server）发送响应Task Json（Json格式的任务字符串）给采集内核（HTTP Client）。
​　S2：在内核的browser进程中，利用建立的带响应的Mojo消息管道，将S1中接收到的Task Json从browser进程传输到render进程。
​　S3：在内核的render进程中，内核数据抽取模块根据Task Json进行具体的内核数据抽取并将抽取后的结果生成Result Json（Json格式的结果字符串）。
​　S4：在内核的render进程中，利用建立的带响应的Mojo消息管道，将S2中生成的Result Json从render进程传输到browser进程。
​　S5：在内核的browser进程中，采集内核（HTTP Client）向采集工具（HTTP Server）发送POST请求，将Result Json发送给采集工具（HTTP Server）进行后续处理。
​　S6和S7：除了将Result Json发送给采集工具（HTTP Server）进行后续处理之外，采集内核还实现了将Result Json通过MySQL Connector写入MySQL数据库进行数据存储。
三、程序代码
1.代码结构
​　以下列出了在Chromium 80.0.3969.0版本上的全部修改文件和新增文件。
（1）路径：src/content/browser
[1]BUILD.gn(修改)：ninja编译配置文件，需添加相关sources和deps。有关GN的详细信息请参考Chromium GN官方文档。
​　[2] frame_host/render_frame_host_impl.h + render_frame_host_impl.cc（修改）：为了建立Mojo作了相应修改。
​　[3] spider_trans文件夹（新增）：Mojo消息管道接口实现文件。
​　[4] browser_interface_binders.cc（修改）：为了建立Mojo作了相应修改。
（2）路径：src/third_party/blink/renderer/core/html/parser
​　[1] BUILD.gn(修改)：ninja编译配置文件，需添加相关sources和deps。有关GN的详细信息请参考Chromium GN官方文档。
​　[2] html_construction_site.h  +  html_construction_site.cc（修改）：程序的入口。
​　[3] html_spider_data.h + html_spider_data.cc（新增）：数据采集功能的主要实现文件。
（3）路径：src/third_party
​　[1] cpp-httplib文件夹（新增）：用于HTTP Client 和 HTTP Server通信的第三方库
​　[2] mysql-connector文件夹（新增）：用于在C++中实现写入数据库MySQL的第三方库。
​    [3] jsoncpp(依赖) ：用于在C++中实现解析json的第三方库，是Chromium自带的。
（4）路径：src/services
​　[1] spider_trans文件夹（新增）：Mojo消息管道接口的接口定义文件。
（5）路径：src/chrome/browser/ui/startup
​　[1] startup_browser_creator_impl.cc（修改）：实现chrome启动后隐藏界面
（6）路径：src/chrome/installer/util
​　实现安装mini_installer禁止生成桌面快捷图标。
​　[1] util_constants.h和util_constants.cc（修改）
​　[2] master_preferences_constants.h（修改）
​　[3] master_preferences.cc（修改）
2.代码调用图
​　下图为简单的主要函数流程图。

git使用说明文档



git安装

下载地址 ： git官网


git详细使用说明文档 git官方文档



安装ssh 免密上传下载代码


生成ssh  【无脑下一步，123…替换成自己的邮箱】

ssh-keygen -t rsa -C "123456789@qq.com"


拷贝SSH Key并添加进SSH设置

cat ~/.ssh/id_rsa.pub 


git 全局设置当前用户

git config --global user.name "用户名"
git config --global user.email "邮箱@qq.com"


下载项目

git clone git@10.10.10.249:project/path.git


项目分支说明

// 查看当前分支
git branch

// 查看所有分支
git branch -a

// 新建分支
git branch newBranch

切换分支
git checkout newBranch

// 删除本地分支
git branch -d newBranch

// 删除远程分支
git push origin --delete newBranch


查看当前修改

// 对比文件更新的具体内容
git diff
// 对比本地仓库的文件更新状态
git status 


下拉/更新项目

git pull


保存并上传到远程仓库

// 保存所有修改到本地暂存区
git add -A

// 提交到本地仓库
git commit -m "commit introduce"

// 上传的到远程仓库master分支
git push origin/master


回退到上一个版本

// 查看历史提交版本
git log

// 回退到指定hash版本
git reset --hard dde8c25694f34acf8971f0782b1a676f39bf0a46 


解决冲突(本地与远程仓库版本不同)


本地有修改，同时保存本地和远程代码

// 挂起/暂存/备份本地修改版本
git stash  
 
// 下拉远程版本
git pull

// 查看挂起版本  查看后 --> stash@{0}
git stash list

// 获取备份
git stash pop stash@{0}

// 对比手动解决冲突


本地有修改，丢弃并覆盖本地修改（慎用）

// 下拉并同步远程仓库版本
git fetch --all

// 使用远程master版本覆盖本地修改
git reset --hard origin/master


合并分支

// 开发结束 切换当前分支为master，并合并开发分支
git merge dev


确定版本（打标签 v1.0/v2.0…）

// 查看所有标签
git tag

// 创建新标签 -a版本号 -m当前版本说明
git tag -a v1.0 -m "my version 1.0"

// 删除标签
git tag -d v1.0

// 上传创建标签到远程仓库
git push origin --tags 

    

            
全局说明
为了更高效,快速的阅读代码, 建议使用 Phpstorm 并且安装 ThinkPHP 这个插件,按住 ctrl 点击鼠标左键 就能直接跳到方法定义的位置
配置

数据库连接配置 / 调试模式






config1



index 模块配置






config2



coldwallet 模块配置 库神冷钱包接口对接, 请不要随意更改






config2



接口
接口验签(所有接口都必须验证签名,才能访问)
注意, 所有请求都需要验证签名, 才能访问





checksign


调试关闭验签
调试时, 可以关闭请求签名验证, 注释以下代码就能关闭签名





close_sign



响应信息多语言配置






lang



如何添加多语言响应信息语言包, 语言包配置文件






languages



根据客户端 发送的 request 的 header中 lang 的值不同响应不同的信息使用  switchlang 选择语言包






设置响应的msg



如何让接口不验证登录
默认情况, 所有的接口都必须验证登录状态, 但是有些接口不需要验证登录, 比如登录接口, 注册接口等





check login status


用户相关接口 ---- UserController

登录, 使用邮箱登录, 使用的是 fastadmin 的 auth
登录的时候注意,使用的是token来保持状态的, 为了保证单点登录,登录的时候必须先清除登录的token
由于ThinkPHP没有firstOrCreate方法,为了保证除程序正常运行, 需要在登录的时候,为用户初始化信息, 初始化方法是 application\index\model\AssetMoney.php 的 initAssets 这个方法






login




注册, 使用邮箱注册, 使用的是 fastadmin 的 auth






register




注销登录






logout



获取当前登录用户的信息






getuserinfo



修改用户头像






updateuserinfo



设置用户的交易密码






update user ex_password



找回登录密码






reset password



我的社区, 我的所有下级






get teammate



获取用户的邀请记录






inviter logs



绑定上级, 绑定推荐人






bind inviter


用户资产相关接口 ---- AssetsController

统计用户的总资产及其转换后的汇率






count moneys



获取用户资产列表






moneys



获取用户资产的增加,减少的记录






money_logs



获取用户资产增加,减少记录的详情






money_log_detail



获取用户所有宠物






pets



获取用户的宠物的 产币记录






output_logs



圈养宠物






feed pet



为用户, 绑定充值, 提现的地址






bind address



转账接口






transfer



提现接口






cash


闯关相关接口 ---- BarrierController
判断当前登录的用户是否符合升级的条件





satisfied


申请闯关, 为当前登录匹配卖家并生成对应的订单






apply pass barrier



获取闯关信息






barrier-info



获取闯关记录






barrer-logs



获取闯关记录详情






upgrade_detail



获取验证过关列表(  就是我邀请的人闯关的记录信息 )






verify_barrier



获取验证详情 (   就是我邀请的人闯关的记录详情信息)






verify  detail 


内容相关接口 ---- ContentController

获取公告列表






advs



获取消息列表






messages



读取信息, 修改信息状态






read msg



获取轮播图列表






carousels



获取详情(0: 轮播图详情 1: 公告详情  2:商品详情  3: 消息详情)






detail


订单相关接口 --- OrdersController

获取订单列表






orders



获取订单详情, 删除订单(取消订单)






order action


提币相关接口 ---- OutputController

用户提币接口






extract


商品相关接口 ---- ProductController

获取海洋世界商品列表






products



海洋世界下单






buy



获取购买商品支持支付的币种, 商品能够用什么币种去购买






supported coins


支付接口

支付的流程

获取订单信息 判断订单信息, 是否能够支付
获取用户选择支付的币种(比如 BTC) 用USDT为基础转换, 转换的比例在 assets_money_conversion 表中
将转换后的币种和数量保存到订单中
判断是否是补货订单, 如果是补货订单(也叫延迟订单) 如果是补货订单去  补货流程





支付1-4步


支付数据修改流程(开启数据库事务):

a. 判断买家的金额是否足够, 如果不足, 支付失败, 返回提示信息

b. 判断卖家的货物是否足够, 如果不够, 先扣除公司的货物,把买家修改为公司用户(也就是说公司给买家宠物, 买家给公司钱), 给卖家生成补货订单(延迟订单)

c. 记录买家, 卖家(这个卖家是指实际卖货的人)资产变动的记录(加了多少钱, 减了多少钱)

d. 支付数据修改之后: 判断是否是升级的订单, 如果是升级订单, 需要进行对应的 升级流程


补货流程

查询出补货订单(卖家, 公司, 卖家等信息)
判断补货订单是否过期(24小时内有效)
下单: 去购买补货订单中同样数量的商品
支付: 走 支付数据修改流程


修改延迟订单的状态信息: 修改为已经完成






补货



升级流程(支付成功后)

判断升级是否是: 普通会员 升级 一级会员

如果不是:   普通会员 升级 一级会员 判断是否能够升级,能就直接升级





判断升级


如果是  普通会员 升级 一级会员 需要 :

a. 判断买家的上级是否有 3 个等级大于等于的 1 级的下级用户

b. 如果有 (判断是否能够升级,能就直接升级) 能就直接去升级

c. 如果上级没有  3 个等级大于等于的 1 级的下级用户 但是 买家已经能够升级了此时不能让买家加直接升级
给买家创建一个延迟升级的记录
当第3个买家(已经有两个延迟升级的买家)购买完成的时候, 给这个卖家的所有 延迟升级 的用户, 全部升级到 1 级





0 => 1



其他接口

获取客户端APP版本号






app_version



获取登录协议, 不需要登录






protocol



发送邮件接口
发送邮件使用的是 PHPMailer 配置信息在后台可配置






send mail







邮件发送配置



定时任务
每隔多长时间执行一次, 注意需要linux的任务计划 crontab 支持





crontab