大数跨境

你的下一个Python项目的终极设置

你的下一个Python项目的终极设置 Python程序员
2020-02-03
0
导读:在这里,我在这个“终极”教程中为你的Python项目带来了各种设置。

不管你是在做一些机器学习/人工智能方面的事情,还是在使用Flask构建web应用程序,或者只是在编写一些快速的Python脚本,为你的项目准备一些模板总是很有用的,这些模板可以满足你的所有需求,即:预定义的目录结构,所有必要的配置文件,如pytest.ini 或 requirements.txt,测试,linting(检查)和静态代码分析设置,CI/CD工具,应用程序的Docker化,以及Makefile的自动化。因此,在这里,我在这个“终极”教程中为你的Python项目带来了各种设置。


注: 这里是我的仓库地址,其中有完整源代码和文档:https://github.com/MartinHeinz/python-project-blueprint


#目录结构


当我在为Golang(在这里)写这样一篇文章时,我很难弄清楚理想的项目结构,但是,使用python,它就非常简单:



让我们概述一下我们在这里有什么,从顶部开始:


  • blueprint - 这是我们的源代码目录,应该由你正在处理的应用程序或包来命名。里面还是像往常一样有__init__.py文件,用来表明这是一个Python包,接下来是__main__.py,当我们想要使用python -m blueprint直接运行我们的应用程序时,它就会被使用。这里的最后一个源文件是app.py,这里只是为了演示。在实际的项目中,你将会有很少的顶级源文件和更多的目录(内部包)。我们稍后将讨论这些文件的内容。最后,我们在这里还有resources目录,它用于你的应用程序可能会需要的任何静态内容,例如图像、密钥库等。

  • tests - 在这个目录中驻留我们的测试套件。我不会在这里讲太多的细节,因为我们会用整个部分来讲测试,但只是简单地说一下:

    ■test_app.py 是一个与源目录中app.py相对应的测试文件

    ■conftest.py 对你来说可能会熟悉一些,如果你曾经使用过Pytest的话。它用于指定Pytest fixture、hook或加载外部插件。

    ■context.py通过操作类路径来帮助我们从blueprint目录导入源代码文件。我们稍后将查看这是如何运行的。 

  • .github - 这是我们这个项目中的最后一个目录。它保存了我们用于CI/CD的GitHub操作的配置。我们有两个文件,第一个是build-test.yml,它负责在每次提交时构建、测试和检查我们的源代码。第二个文件是push.yml,每次我们在GitHub上创建tag/release时,它会将我们构建的应用程序提交到GitHub包注册表。关于本目录的更多信息将在另一篇博文中讨论。

  • Makefile -除了目录之外,我们的项目中还有几个顶层文件,首先是Makefile,它包含一些目标文件,这些目标文件将帮助我们自动执行常见的任务,比如构建、测试、检查或清理项目

  • configure_project.sh - 这是一个为你设置项目的非常方便的脚本。它实际上是将项目模板中的虚值重命名并替换为实际值,如项目名或包名。很方便,对吧?


这里的其余文件是我们将在这个项目中使用的所有工具的配置文件。让我们跳到下一节,探索它们的功能和内容。


#配置文件


在设置Python项目时,有一件事可能会变得非常混乱,那就是当你在使用pylint、coverage.py、flake8等工具时,你最终得到的配置文件。这些工具都希望拥有自己的文件,通常是像.flake8或.coveragerc之类的东西,这会在你的项目的根目录中创建许多不必要的混乱。为了避免这种情况,我把所有这些文件都合并到一个单个的文件setup.cfg中:



如果你不熟悉这里使用的所有工具,我将快速描述一下它们:


  • Flake8 - 是一个在你的项目中增强代码风格的工具——换句话说——它的linter类似于pylint,我们也将使用它。为什么使用它们两个?它们确实是重叠的,但是它们都有一些另一个所没有的规则,所以根据我的经验,它们都是值得使用的。

  • Bandit ——是一个查找Python代码中常见安全问题的工具。它通过从代码中创建AST(抽象语法树)并在其节点上运行插件来工作的。开发人员通常不是安全专家,而且我们每个人都会犯各种各样的错误,所以有一个工具可以为我们发现其中的一些安全错误是很不错的。

  • Coverage.py - 是一个测量Python程序代码覆盖率的工具。当我们使用Pytest运行我们的测试套件时,它会被触发,并从测试运行中生成覆盖率报告。这些报告可以是终端输出形式的,也可以是XML格式的,然后可以被CI工具使用。


有了这些,让我们来回顾一下setup.cfg中的内容。对于Flake8,我们定义了排除模式,这样我们就不会通过linit分析我们不关心的代码。它的下面是一个空的ignore部分,以防我们需要忽略一些全局规则。我们还将最大行长度设置为120,因为在我看来,保持行长度为80对于当今屏幕的大小是不合理的。最后一行将McCabe复杂度阈值设置为10,如果你不熟悉圈复杂度,你可以在这里了解更多。


接下来是Bandit,我们在这里配置的是目标目录,它是我们包的名称。这样做是为了避免在命令行上指定目标。


然后就是Coverage.py。首先,我们启用分支覆盖,这意味着在你的程序中的一行可以跳转到多个下一行的地方,Coverage.py会追踪哪些目标行是实际被访问的。接下来,我们省略了一些不应该或者不能包含在覆盖率测量中的文件,比如测试本身或者虚拟环境文件。我们还排除了特定的行,例如标记有pragma: no cover 注释的行。最后的Coverage.py配置行告诉工具将生成的报告存储在reports目录中。这个目录是自动创建的,如果它还不存在的话。


我们需要配置的最后一个工具是Pylint,配置非常广泛,大约有100多行……因此,我将省略这个工具的配置,并在这里指出其源代码,以及在Pylint存储库中注释和解释pylintrc。


我们浏览了setup.cfg中的所有工具,但还有一个不能添加到setup.cfg的工具,那就是Pytest——尽管Pytest文档告诉你可以使用setup.cfg,但这并不是真的…根据这个问题来看,使用setup.cfg这个选项是不被赞成的,并且会产生一些如插值错误之类的bug,这些bug是无法修复的,因此,我们也需要使用pytest.ini文件来配置Pytest:



我们在这里做的第一件事是设置一堆命令行参数——我们在终端输出中启用了色彩,然后我们为blueprint目录启用了覆盖率报告,在此之后,我们又启用了XML和stdout(term)覆盖率报告的生成。最后两个参数(-ra)告诉Pytest对未通过的测试输出简短摘要。


在下一行,我们有filterwarnings选项,它允许我们在输出中禁用一些烦人的警告,例如来自某个我们无法控制的一些库的弃用警告。


配置的其余部分设置了日志记录。第一个设置只是打开日志记录和其他3个配置级别、格式和日期时间格式。比解释格式配置更简单的是查看输出本身,这将在下一节中显展示。


将所有设置保存在pytest.ini中之后,我们运行测试套件所需要做的就是运行pytest,甚至不需要包参数!


我们最后一个实际的配置文件是requirement.txt,它包含我们的依赖项列表。在这个文件中你只能找到Python包的列表,每行具有一个包的可选版本。如注释所示,包版本是可选的,但我强烈建议你在requirements.txt中锁定版本,以避免在构建和部署期间下载更新的、不兼容的包,并最终破坏你的应用程序的情况。


剩下的两个文件实际上不是配置文件,而是我们的Dockerfile,即分别用于开发和生产镜像的dev.Dockerfile 和 prod.Dockerfile。我将暂时不讨论它们,因为我们将在另一篇讨论CI/CD和部署的文章中探究它们。当然,你可以在GitHub仓库中查看这些文件——https://github.com/MartinHeinz/python-project-blueprint/blob/master/dev.Dockerfile  。


#实际的源代码


我们已经做了很多,甚至没有提到我们的应用程序的源代码,但我认为是时候看看项目框架中的那几行代码了:



这个blueprint中唯一实际的源代码就是这个带有静态方法的类。这是真正需要的,这样我们就可以运行一些东西,得到一些输出并测试它。这也可以作为整个应用程序的入口点。在实际项目中,你可以使用run()方法来初始化你的应用程序或web服务器。


那么,我们如何实际运行这段代码呢?



专门命名为文件__main__.py中的这个简短的代码片段是我们的项目所需要的,这样我们就可以使用python -m blueprint运行整个包。这个文件和它的内容的一个好处是,它只能用那个命令来运行,因此,如果我们只想从这个包的源代码中导入一些东西而不运行整个包,那么我们就可以这样做而不触发Blueprint.run()。


在我们的包中还有一个特殊的文件,那就是__init__.py文件。通常,你会让它为空,只使用它来告诉Python该目录是包。但是在这里,我们将使用它从我们的包中导出类、变量和函数。



如果没有上面这一行,你就不能从这个包的外部调用Blueprint.run()。通过这种方式,我们可以避免人们使用不应该公开的代码的内部部分。


这就是我们包的代码,但是测试呢?首先,让我们看看context.py。



通常情况下,当你使用某些包时,你会像import blueprint或from blueprint import Blueprint那样导入它,以在我们的测试中模拟它,从而使它尽可能接近我们使用context.py将包导入到我们的测试上下文的实际用法。将包导入我们的测试上下文。我们还将项目的根目录插入到了系统路径。在使用pytest运行测试时,这实际上并不是必需的,但是如果你在没有包括sys.path.insert...的情况下,使用python ./tests/context.py或可能使用unittest直接运行context.py时,那你就会得到ModuleNotFoundError: No module named 'blueprint',所以这一行有点保险策略。


现在,让我们看看示例测试:



我们这里只有一个测试,它使用内置的称为capsys(捕获系统输出)的Pytest fixture来检查Blueprint.run()的标准输出。那么,当我们运行测试套件时会发生什么?



我从输出中裁剪了几行,以便你能更好地看到它的相关部分。这里要注意什么呢?好吧,我们的测试通过了!除此之外,我们可以看到覆盖率报告,并且我们也可以看到该报告按照pytest.ini中所配置的那样被写入了coverage.xml。我们在输出中还有一样东西是来自conftest.py的两条日志消息。这是关于什么的呢?


你可能已经注意到,除了capsys fixture外,我们还在小测试的参数中使用了example_fixture。这个fixture位于conftest.py中,与我们创建的所有自定义fixture一样:



顾名思义,这实际上只是一个示例fixture。它所做的只是记录一条消息,然后让测试运行,最后再记录一条消息。关于conftest.py的比较有趣的事情是,它是由Pytest自动发现的,所以你甚至不需要将它导入到你的测试文件中。如果你想了解更多有关它的信息,你可以查看我之前的关于Pytest的文章或其文档。


#一个万能命令


如果我们要分别地运行每个工具,并且必须记住它们的参数,即使它们总是相同的,这将是非常困难的。如果以后我们决定将所有这些工具都放到CI/CD(下一篇文章!)中,那它也会是相当恼人的,对吗?所以,让我们用Makefile来简化事情:



在这个Makefile中,我们有4个目标。首先是run,它会使用我们在源文件夹的根目录中创建的__main__.py来运行我们的应用程序。接下来是test,它只运行pytest。就是这么简单,这要感谢pytest.ini中的所有配置。这里最长的目标- lint -会运行我们所有的linting工具。首先,它会对项目中的所有.py文件运行pylint,包括测试文件。在那之后,它会运行flake8,并且最后运行bandit。对于这两个工具,它只针对blueprint目录中的源代码运行。如果这些工具中的任何一个发现我们的代码有问题,它将以非零代码退出,这意味着目标将会失败,这在CI/CD中非常有用。这个文件中的最后一个目标是clean,它会清理我们的项目——它会删除所有由前面提到的工具生成的文件。


#结论


在本文中,我们已经构建了项目框架,它可以用于任何类型的你正在处理或考虑的Python项目,所以如果你想试试它或再深入了解一下,那你可以在我的仓库中查看源代码:https://github.com/MartinHeinz/python-project-blueprint  。仓库中还包括关于如何使用方便的脚本设置你的项目的信息,以及更多的文档。如果你喜欢这类内容,请随时以问题的形式进行反馈/建议,你也可以进行好评。


在下一篇文章中,我们将研究如何将CI/CD添加到GitHub操作和GitHub包注册表中。我们还将Docker化我们的项目,创建可调试的和优化过的用于生产的Docker映像,并使用CodeClimate和SonarCloud添加更多的代码质量工具。


资源


示例Python模块仓库:https://github.com/navdeep-G/samplemod 

Pytest文档:https://docs.pytest.org/en/latest/contents.html 

Python代码质量管理局:https://github.com/PyCQA 


英文原文:https://martinheinz.dev/blog/14
译者:一瞬

【声明】内容源于网络
0
0
Python程序员
1234
内容 2525
粉丝 0
Python程序员 1234
总阅读0
粉丝0
内容2.5k