在本教程中探索了如何创建新的 Python Poetry 项目以及如何将 Poetry 添加到现有项目中.docx

在本教程中，探索了如何创建新的PythonPoetry项目以及如何将Poetry添加到现有项目中。可以在下方选择您的操作系统以使用相应的命令视窗LinuxmacOSPSC:(Invoke-WebRequest-Uris:/raw.githubusercontent/python-poetry/poetry/master/install-poetry.py-UseBasicParsing).Content|python-假如您使用的是Windows那么您可以使用Invoke-Webrequest带有-UseBasicParsing选项的cmdlet将恳求的URL的内容下载到标准输出流(stdout)。随着管道字符|你移交输出到标准输入流标准输入的python。在这种情况下您将的内容通过管道install-poetry.py传输到Python解释器。注意有些用户在Windows10上使用PowerShell命令时会报告错误。在输出中您应该看到安装完成的消息。您可以poetry-version在终端中运行以查看是否poetry有效。此命令将显示您当前的Poetry版本。假如要更新Poetry那么可以运行poetryselfupdate.PythonPoetry入门安装Poetry后是时候看看Poetry是怎样工作的了。在本节中您将学习怎样开场一个新的Poetry工程和怎样将Poetry添加到现有工程中。您还将看到工程构造并检查pyproject.toml文件。创立一个新的Poetry工程您可以使用new命令以及工程名称作为参数来创立新的Poetry工程。在本教程中该工程称为rp-poetry.创立工程然后进入新创立的目录$poetrynewrp-poetry$cdrp-poetry通过运行poetrynewrp-poetry您可以创立一个名为的新文件夹rp-poetry/。当您查看文件夹内部时您会看到一个构造rp-poetry/rp_poetry/_init_.pytests/_init_.pytest_rp_poetry.pyREADME.rstpyproject.tomlPoetry会自动为您标准化包名。它将-工程名称中的破折号()转换_为文件夹名称中的下划线()rp_poetry/。否那么Python中将不允许使用该名称因此您无法将其作为模块导入。为了更好地控制创立包名称您可以使用该-name选项以不同于工程文件夹的方式命名$poetrynewrp-poetry-namerealpoetry假如您更喜欢将源代码存储在额外的src/父文件夹中那么Poetry可以让您使用以下-src标志来遵守该约定$poetrynew-srcrp-poetry$cdrp-poetry通过添加-src标志您创立了一个名为的文件夹src/其中包含您的rp_poetry/目录rp-poetry/src/rp_poetry/_init_.pytests/_init_.pytest_rp_poetry.pyREADME.rstpyproject.toml创立新的Poetry工程时您将立即收到一个根本的文件夹构造。检查工程构造该rp_poetry/子文件夹本身是不是很壮观呢。在这个目录中你会找到一个_init_.py包含你的包版本的文件#rp_poetry/_init_.py_version_0.1.0当您跳到tests/文件夹并翻开时test_rp_poetry.py您会注意到它rp_poetry已经是可导入的#tests/test_rp_poetry.pyfromrp_poetryimport_version_deftest_version():assert_version_0.1.0Poetry还为该工程添加了第一个测试。该test_version()函数检查的_version_变量是否rp_poetry/_init_.py包含预期的版本。但是该_init_.py文件并不是您定义包版本的唯一位置。另一个位置是pyproject.toml文件。使用pyproject.toml文件使用Poetry最重要的文件之一是pyproject.toml文件。这个文件不是Poetry的创造。这是PEP518中定义的配置文件标准此PEP指定Python软件包应怎样指定它们具有的构建依赖项以执行其选择的构建系统。作为本标准的一局部为软件包引入了一个新的配置文件用于指定它们的构建依赖项期望一样的配置文件将用于将来的配置细节。来源考虑了上面引用中提到的“新配置文件的几种文件格式。最后他们决定采用TOML格式即TomsObviousMinimalLanguage的缩写。在他们看来TOML足够灵敏比其他选项YAML、JSON、CFG或者INI具有更好的可读性以及更少的复杂性。要查看TOML的外观请翻开pyproject.toml文件1#pyproject.toml3tool.poetry4namerp-poetry5version0.1.06description7authorsPhilippphilipprealpython9tool.poetry.dependencies10python3.912tool.poetry.dev-dependencies13pytest5.215build-system16requirespoetry-core1.0.017build-backendpoetry.core.masonry.api您可以在pyproject.toml文件中看到四个局部。这些局部称为表。它们包含诸如Poetry之类的工具识别以及用于依赖项管理或者构建例程的指令。假如表名是特定于工具的那么必须以tool.为前缀。通过使用这样的子表您可以为工程中的不同工具添加讲明。在这种情况下只有tool.poetry.但是你可能会看到这样的例子tool.pytest.ini_options为pytest在其他工程中。在tool.poetry上面第3行的子表中您可以存储有关您的Poetry工程的一般信息。您的可用键由Poetry定义。固然有些键是可选的但您必须指定四个键name:你的包名version:包的版本最好遵循语义版本控制description您的包裹的简短描绘authors:列表格式nameemail第tool.poetry.dependencies9行以及tool.poetry.dev-dependencies第12行的子表对于您的依赖项管理至关重要。在下一局部向Poetry工程添加依赖项时您将解析有关这些子表的更多信息。如今重要的是要认识到的包相关性以及开展依赖之间的区别。该pyproject.toml文件的最后一个表位于第build-system15行。该表定义了Poetry以及其他构建工具可以使用的数据但由于它不是特定于工具的因此它没有前缀。Poetry创立了pyproject.toml具有两个键的文件requires构建包所需的依赖项列表使此键成为必需build-backend用于执行构建经过的Python对象假如您想更多地解析pyproject.toml文件的这一局部那么您可以通过浏览PEP517中的源代码树来解析更多信息。当您使用Poetry开场一个新工程时这就是pyproject.toml您开场的文件。随着时间的推移您将添加有关您的包以及您正在使用的工具的配置详细信息。随着Python工程的增长您的pyproject.toml文件也会随之增长。对于子表tool.poetry.dependencies以及tool.poetry.dev-dependencies.在下一节中您将解析怎样扩展这些子表。使用PythonPoetry一旦你设置了一个Poetry工程真正的工作就可以开场了。一旦Poetry到位您就可以开场编码。在此经过中您将解析Poetry怎样为您提供虚拟环境并处理您的依赖项。使用Poetry的虚拟环境当您开场一个新的Python工程时创立一个虚拟环境是一种很好的做法。否那么您可能会混淆来自不同工程的不同依赖项。使用虚拟环境是Poetry的核心功能之一它永远不会干扰您的全局Python安装。但是Poetry不会在您启动工程时立即创立虚拟环境。您可以通过让Poetry列出连接到当前工程的所有虚拟环境来确认Poetry尚未创立虚拟环境。假如你还没有cd进入rp-poetry/然后运行一个命令$poetryenvlist目前不应该有任何输出。当您运行某些命令时Poetry会一路创立一个虚拟环境。假如您想更好地控制虚拟环境的创立那么您可能决定明确告诉Poetry您要为其使用哪个Python版本然后从那里开场$poetryenvusepython3使用此命令您将使用与安装Poetry一样的Python版本。使用python3的作品当你在你的Python可执行程序PATH。注意或您可以将绝对途径传递给Python可执行文件。它应该与您可以在pyproject.toml文件中找到的Python版本约束相匹配。假如没有那么您可能会遇到费事因为您使用的Python版本与工程所需的版本不同。在您的环境中运行的代码在另一台机器上可能有问题。更糟糕的是外部包通常依赖于特定的Python版本。因此安装包的用户可能会收到错误消息因为您的依赖项版本与其Python版本不兼容。当你运行时envuse你会看到一条消息Creatingvirtualenvrp-poetry-AWdWY-py3.9in/Library/Caches/pypoetry/virtualenvsUsingvirtualenv:/Library/Caches/pypoetry/virtualenvs/rp-poetry-AWdWY-py3.9如您所见Poetry为您的工程环境构建了一个唯一名称。该名称包含工程名称以及Python版本。中间看似随机的字符串是您的父目录的哈希值。通过中间的这个唯一字符串Poetry可以处理系统上具有一样名称以及一样Python版本的多个工程。这很重要因为默认情况下Poetry在同一个文件夹中创立所有虚拟环境。Poetry无需任何其他配置在virtualenvs/Poetry缓存目录的文件夹中创立虚拟环境假如要更改默认缓存目录那么可以编辑Poetry的配置。当您已经在使用virtualenvwrapper或者其他第三方工具来管理您的虚拟环境时这会很有用。要查看当前配置包括已配置的cache-dir您可以运行以下命令$poetryconfig-list通常您不必更改此途径。假如您想解析有关与Poetry的虚拟环境交互的更多信息那么Poetry文档包含有关管理环境的一章。只要您在工程文件夹中Poetry就会使用与之关联的虚拟环境。假如您有疑问可以envlist再次运行以下命令检查虚拟环境是否已激活$poetryenvlist这将显示类似rp-poetry-AWdWY-py3.9(Activated).有了激活的虚拟环境您就可以开场管理一些依赖项并看到Poetry的魅力了。声明你的依赖Poetry的一个关键元素是它对依赖项的处理。在开场之前先看一下文件中的两个依赖表pyproject.toml#rp_poetry/pyproject.toml(Excerpt)tool.poetry.dependenciespython3.9tool.poetry.dev-dependenciespytest5.2当前为您的工程声明了两个依赖项。一个是Python本身。另一个是pytest一个广泛使用的测试框架。正如您之前看到的您的工程包含一个tests/文件夹以及一个test_rp_poetry.py文件。使用pytest作为依赖项Poetry可以在安装后立即运行您的测试。注意在编写本教程时pytest使用Python3.10运行Poetry不起作用。Poetry安装了一个与Python3.10不兼容的pytest版本。Poetry开发人员已经意识到这个问题它将随着Poetry1.2的发布而得到修复。确保您在rp-poetry/工程文件夹中并运行命令$poetryinstall使用该install命令Poetry检查您的pyproject.toml文件中的依赖项然后解析并安装它们。当您有许多依赖项需要使用不同版本的不同第三方包时解析局部尤其重要。在安装任何包之前Poetry会确定哪个版本的包知足其他包设置为其要求的版本限制。除了pytest它的要求之外Poetry还安装了工程本身。这样您可以立即导入rp_poetry到您的测试中#tests/test_rp_poetry.pyfromrp_poetryimport_version_deftest_version():assert_version_0.1.0安装工程包后您可以导入rp_poetry测试并检查_version_字符串。随着pytest安装您可以使用poetryrun命令来执行测试1$poetryrunpytest2testsessionstarts3platformdarwin-Python3.9.1,pytest-5.4.3,py-1.10.0,pluggy-0.13.14rootdir:/Users/philipp/RealPython/rp-poetry5collected1item91passedin0.01s您当前的测试已成功运行因此您可以放心地继续编码。但是假如您仔细观察第3行就会发现有些奇怪。它讲pytest-5.4.35.2不像pyproject.toml文件中所讲的那样。接得好回首一下文件中的pytest依赖项pyproject.toml如下所示#rp_poetry/pyproject.toml(Excerpt)tool.poetry.dev-dependenciespytest5.2前面的插入符号()5.2具有特定的含义它是Poetry提供的版本约束之一。这意味着Poetry可以安装与版本字符串最左边的非零数字匹配的任何版本。这意味着5.4.3允许使用。版本6.0将不被允许。当Poetry尝试解析依赖版本时像插入符号这样的符号将变得很重要。假如只有两个要求这并不太难。你声明的依赖越多它就越复杂。让我们看看Poetry怎样通过将新包安装到您的工程中来处理这个问题。安装带有Poetry的包您pip之前可能使用过安装不属于Python标准库的包。假如您pipinstall使用包名作为参数运行那么pip在PythonPackageIndex上查找包。您可以以同样的方式使用Poetry。假如你想在requests你的工程中添加一个外部包那么你可以运行一个命令$poetryaddrequests通过运行poetryaddrequests您正在将最新版本的requests库添加到您的工程中。您可以使用版本约束requests2.1或requests2.24假如您想更详细。当您不添加任何约束时Poetry将始终尝试安装最新版本的软件包。有时您只想在开发环境中使用某些包。使用pytest您已经发现其中之一。另一种常见的库包括一个代码格式化像黑色一个文档生成等斯芬克斯以及类似的一个静态分析工具pylint的Flake8mypy或者coverage.py。要明确告诉Poetry一个包是一个开发依赖项您可以poetryadd使用该-dev选项运行。您还可以使用速记-D选项它与以下内容一样-dev$poetryaddblack-D您添加requests为工程依赖项以及black开发依赖项。Poetry在后台为您做了一些事情。一方面它将您声明的依赖项添加到pyproject.toml文件中#rp_poetry/pyproject.toml(Excerpt)tool.poetry.dependenciespython3.9requests2.26.0tool.poetry.dev-dependenciespytest5.2black21.9b0Poetry将该requests包作为工程依赖项添加到tool.poetry.dependencies表中同时将其black作为开发依赖项添加到tool.poetry.dev-dependencies.区分工程依赖项以及开发依赖项可以防止安装用户不需要运行程序的需求。开发依赖项仅与您的包的其他开发人员相关他们祈望pytest使用black.当用户安装您的软件包时他们只会安装requests它。注意您可以更进一步并声明可选的依赖项。当您想让用户选择安装一个不需要但增强您的包的特定数据库适配器时这会很方便。您可以在Poetry文档中解析有关可选依赖项的更多信息。除了对pyproject.toml文件的更改之外Poetry还创立了一个名为poetry.lock.在此文件中Poetry会跟踪您在工程中使用的所有包以及确切版本。处理poetry.lock当您运行该poetryadd命令时Poetry会自动更新pyproject.toml并固定poetry.lock文件中的已解析版本。但是您不必让Poetry完成所有工作。您可以手动向pyproject.toml文件添加依赖项并在之后锁定它们。引脚依赖关系poetry.lock假如您想使用Python构建网络爬虫那么您可能需要使用BeautifulSoup来解析您的数据。将其添加到文件中的tool.poetry.dependencies表中pyproject.toml#rp_poetry/pyproject.toml(Excerpt)tool.poetry.dependenciespython3.9requests2.26.0beautifulsoup44.10.0通过添加beautifulsoup44.10.0您告诉Poetry它应该完全安装这个版本。当您向pyproject.toml文件添加需求时它尚未安装。只要poetry.lock你的工程中没有文件存在你就可以poetryinstall在手动添加依赖后运行因为Poetry会先查找poetry.lock文件。假如没有找到Poetry将解析pyproject.toml文件中列出的依赖项。一旦poetry.lock文件存在Poetry将依赖该文件来安装依赖项。仅运行poetryinstall会触发警告提示两个文件不同步并会产生错误因为Poetry尚不知道beautifulsoup4工程中的任何版本。要将pyproject.toml文件中手动添加的依赖项固定到poetry.lock您必须首先运行以下poetrylock命令$poetrylockUpdatingdependenciesWritinglockfile通过运行poetrylockPoetry处理pyproject.toml文件中的所有依赖项并将它们锁定到poetry.lock文件中。诗歌并不止于此。运行时poetrylockPoetry还会递归遍历并锁定您的直接依赖项的所有依赖项。注意poetrylock假如有合适您的版本限制的新版本可用该命令还会更新您现有的依赖项。假如您不想更新poetry.lock文件中已有的任何依赖项那么必须将-no-update选项添加到poetrylock命令中$poetrylock-no-update在这种情况下Poetry仅解析新的依赖项但poetry.lock不会更改文件中的任何现有依赖项版本。如今您已经固定了所有依赖项是时候安装它们以便您可以在您的工程中使用它们。安装依赖项poetry.lock假如您按照上一节中的步骤操作那么您已经安装pytest并black使用了该poetryadd命令。您还锁定了beautifulsoup4但您还没有安装BeautifulSoup。要验证beautifulsoup4尚未安装请使用以下命令翻开Python解释器poetryrun$poetryrunpython3执行poetryrunpython3将在Poetry的环境中翻开一个交互式REPL会话。首先尝试导入requests.这应该完美无缺。然后尝试importingbs4这是BeautifulSoup的模块名称。这应该会引发错误因为尚未安装BeautifulSoupimportrequestsimportbs4Traceback(mostrecentcalllast):Filestdin,line1,inmoduleModuleNotFoundError:Nomodulenamedbs4正如预期的那样您可以requests毫无困难地导入并且bs4找不到模块。通过键入exit()并点击退出交互式Python解释器Enter。使用poetrylock命令锁定依赖项后您必须运行该poetryinstall命令以便您可以在工程中实际使用它们$poetryinstallInstallingdependenciesfromlockfilePackageoperations:2installs,0updates,0removalsInstallingsoupsieve(2.2.1)Installingbeautifulsoup4(4.10.0)Installingthecurrentproject:rp-poetry(0.1.0)通过运行poetryinstallPoetry读取poetry.lock文件并安装其中声明的所有依赖项。如今bs4已准备好在您的工程中使用。要对此进展测试请输入poetryrunpython3并导入bs4Python解释器importbs4bs4._version_4.10.0完美的这次没有错误并且您拥有您声明确实切版本。这意味着BeautifulSoup已正确固定在您的poetry.lock文件中已安装在您的工程中并且可以使用了。要列出工程中的可用包并检查它们的详细信息您可以使用该show命令。当您使用-help标志运行它时您将看到怎样使用它$poetryshow-help要检查包您可以使用show包名称作为参数可以以使用-tree选项将所有依赖项以树的形式列出。这将帮助您查看工程的嵌套需求。更新依赖为了更新您的依赖项Poetry根据两种情况提供了不同的选项更新版本约束内的依赖项。更新版本约束之外的依赖项。您可以在pyproject.toml文件中找到版本限制。当新版本的依赖项仍然知足您的版本限制时您可以使用以下update命令$poetryupdate该update命令将在版本限制内更新所有包及其依赖项。之后Poetry将更新您的poetry.lock文件。假如你想更新一个或者多个特定的包那么你可以将它们作为参数列出$poetryupdaterequestsbeautifulsoup4使用此命令Poetry将搜索知足文件中列出的版本限制的新版本requests以及新版本。然后它将解析您工程的所有依赖项并将版本固定到您的文件中。您的文件将保持不变因为列出的约束仍然有效。beautifulsoup4pyproject.tomlpoetry.lockpyproject.toml假如要使用比pyproject.toml文件中定义的版本更高的版本来更新依赖项那么需要pyproject.toml事先调整文件。另一种选择是add使用版本约束或者latest标签运行命令$poetryaddpytestlatest-dev当您运行add带有latest标记的命令时它会查找包的最新版本并更新您的pyproject.toml文件。包含latest标签或者版本约束对于使用该add命令至关重要。假如没有它您会收到一条消息说明该包已存在于您的工程中。另外不要忘记-dev为开发依赖项添加标志。否那么您会将包添加到常规依赖项中。添加新版本后您必须运行install您在上一节中学到的命令。只有这样您的更新才会被锁定到poetry.lock文件中。假如您不确定更新会为您的依赖项引入哪些基于版本的更改您可以使用该-dry-run标志。此标志适用于命令update以及add命令。它在您的终端中显示操作而不执行任何操作。这样您可以平安地发现版本更改并决定哪种更新方案最合适您。区分pyproject.toml以及poetry.lock固然pyproject.toml文件中的版本要求可能很宽松但Poetry会锁定您在poetry.lock文件中实际使用的版本。这就是为什么在使用Git时应该提交此文件的原因。通过poetry.lock在Git存储库中提供文件您可以确保所有开发人员都将使用所需软件包的一样版本。当您遇到包含poetry.lock文件的存储库时最好使用Poetry。使用poetry.lock您可以确保您使用的版本与其他开发人员使用的版本完全一样。假如其他开发人员不使用Poetry您可以将其添加到未使用Poetry设置的现有工程中。将poetry添加到现有工程很有可能您的工程不是从poetrynew命令开场的。或您可能继承了一个不是用Poetry创立的工程但如今您想使用Poetry进展依赖管理。在这些类型的情况下您可以将Poetry添加到现有的Python工程中。添加pyproject.toml到脚本文件夹假如您的工程只包含一些Python文件那么您仍然可以添加Poetry作为将来构建的根底。在这个例子中只有一个文件hello.py#rp-hello/hello.pyprint(HelloWorld!)这个脚本唯一能做的就是输出字符串HelloWorld!。但也许这只是一个宏伟工程的开场因此您决定将Poetry添加到您的工程中。poetrynew您将使用以下poetryinit命令而不是使用之前的命令$poetryinitThiscommandwillguideyouthroughcreatingyourpyproject.tomlconfig.Packagenamerp-hello:rp-helloVersion0.1.0:Description:MyHelloWorldExampleAuthorPhilippphilipprealpython,ntoskip:License:CompatiblePythonversions3.9:Wouldyouliketodefineyourmaindependenciesinteractively?(yes/no)yesnoWouldyouliketodefineyourdevelopmentdependenciesinteractively?(yes/no)yesnoGeneratedfile该poetryinit命令将启动交互式会话以创立pyproject.toml文件。Poetry为您提供了大多数需要设置的配置的建议您可以按下Enter以使用它们。当您不声明任何依赖项时pyproject.tomlPoetry创立的文件如下所示#rp-hello/pyproject.tomltool.poetrynamerp-helloversion0.1.0descriptionMyHelloWorldExampleauthorsPhilippphilipprealpythontool.poetry.dependenciespython3.9tool.poetry.dev-dependenciesbuild-systemrequirespoetry-core1.0.0build-backendpoetry.core.masonry.api内容看起来与您在前几节中经历的例如相似。如今您可以使用Poetry工程提供的所有命令。有了pyproject.toml文件您如今可以运行脚本$poetryrunpython3hello.pyCreatingvirtualenvrp-simple-UCsI2-py3.9in/Library/Caches/pypoetry/virtualenvsHelloWorld!因为Poetry没有找到任何可以使用的虚拟环境所以它在执行您的脚本之前创立了一个新环境。执行此操作后它会显示您的HelloWorld!消息而没有任何错误。这意味着您如今有一个正在运行的Poetry工程。使用现有requirements.txt文件有时您的工程已经有一个requirements.txt文件。看看requirements.txt这个Python网络爬虫的文件$catrequirements.txtbeautifulsoup44.9.3certifi2020.12.5chardet4.0.0idna2.10requests2.25.1soupsieve2.2.1urllib31.26.4使用该cat实用程序您可以读取文件并将内容写入标准输出。在本例中它显示了网络爬虫工程的依赖项。使用创立Poetry工程后poetryinit您可以将该cat实用程序与以下poetryadd命令结合使用$poetryaddcatrequirements.txtCreatingvirtualenvrp-require-0ubvZ-py3.9in/Library/Caches/pypoetry/virtualenvsUpdatingdependenciesWritinglockfilePackageoperations:7installs,0updates,0removalsInstallingcertifi(2020.12.5)Installingchardet(4.0.0)Installingidna(2.10)Installingsoupsieve(2.2.1)Installingurllib3(1.26.4)Installingbeautifulsoup4(4.9.3)Installingrequests(2.25.1)当需求文件像这样简单时使用poetryadd以及cat可以为您节省一些手开工作。requirements.txt然而有时文件会更复杂一些。在这些情况下您可以执行测试运行并查看结果或手动将需求添加到文件中的tool.poetry.dependencies表中pyproject.toml。要查看您的构造pyproject.toml是否有效您可以在poetrycheck之后运行。创立requirements.txt自poetry.lock在某些情况下您必须有一个requirements.txt文件。例如也许您想在Heroku上托管您的Django工程。对于这种情况Poetry提供了export命令。假如你有一个Poetry工程你可以requirements.txt从你的poetry.lock文件中创立一个文件$poetryexport-outputrequirements.txtpoetryexport以这种方式使用该命令会创立一个requirements.txt包含散列以及环境标记的文件。这意味着您可以确保处理与poetry.lock文件内容类似的非常严格的要求。假如您还想包含您的开发依赖项您可以添加-dev到命令中。要查看所有可用选项您可以选中poetryexport-help。命令参考本教程向您介绍了Poetry的依赖管理。在此经过中您使用了一些Poetry的命令行界面(CLI)命令您可以查看PoetryCLI文档以解析有关上述命令以及Poetry提供的其他命令的更多信息。您还可以poetry-help直接在终端中运行以查看信息在本教程中您探究了怎样创立新的PythonPoetry工程和怎样将Poetry添加到现有工程中。Poetry的一个关键局部是pyproject.toml文件。与结合使用poetry.lock您可以确保安装工程所需的每个包确实切版本。当您跟踪poetry.lockGit存储库中的文件时您还要确保工程中的所有其他开发人员在他们的机器上安装一样的依赖项版本。