Package: nwpoetry
Poetry: Dependency Management for PythonPoetry helps you declare, manage and install dependencies of Python projects,
ensuring you have the right stack everywhere.It supports Python 2.7 and 3.4+.InstallationPoetry provides a custom installer that will installpoetryisolated
from the rest of your system by vendorizing its dependencies. This is the
recommended way of installingpoetry.curl-sSLhttps://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py|pythonAlternatively, you can download theget-poetry.pyfile and execute it separately.If you want to install prerelease versions, you can do so by passing--previewtoget-poetry.py:pythonget-poetry.py--previewSimilarly, if you want to install a specific version, you can use--version:pythonget-poetry.py--version0.7.0Usingpipto installpoetryis also possible.pipinstall--userpoetryBe aware, however, that it will also install poetry's dependencies
which might cause conflicts.UpdatingpoetryUpdating poetry to the latest stable version is as simple as calling theself:updatecommand.poetryself:updateIf you want to install prerelease versions, you can use the--previewoption.poetryself:update--previewAnd finally, if you want to install a specific version you can pass it as an argument
toself:update.poetryself:update0.8.0Enable tab completion for Bash, Fish, or Zshpoetrysupports generating completion scripts for Bash, Fish, and Zsh.
Seepoetry help completionsfor full details, but the gist is as simple as using one of the following:# Bashpoetrycompletionsbash>/etc/bash_completion.d/poetry.bash-completion# Bash (macOS/Homebrew)poetrycompletionsbash>$(brew--prefix)/etc/bash_completion.d/poetry.bash-completion# Fishpoetrycompletionsfish>~/.config/fish/completions/poetry.fish# Zshpoetrycompletionszsh>~/.zfunc/_poetry# Zsh (macOS/Homebrew)poetrycompletionszsh>$(brew--prefix)/share/zsh/site-functions/_poetryNote:you may need to restart your shell in order for the changes to take
effect.Forzsh, you must then add the following line in your~/.zshrcbeforecompinit(not for homebrew setup):fpath+=~/.zfuncIntroductionpoetryis a tool to handle dependency installation as well as building and packaging of Python packages.
It only needs one file to do all of that: the new,standardizedpyproject.toml.In other words, poetry usespyproject.tomlto replacesetup.py,requirements.txt,setup.cfg,MANIFEST.inand the newly addedPipfile.[tool.poetry]name="my-package"version="0.1.0"description="The description of the package"license="MIT"authors=["Sébastien Eustace <sebastien@eustace.io>"]readme='README.md'# Markdown files are supportedrepository="https://github.com/sdispater/poetry"homepage="https://github.com/sdispater/poetry"keywords=['packaging','poetry'][tool.poetry.dependencies]python="~2.7 || ^3.2"# Compatible python versions must be declared heretoml="^0.9"# Dependencies with extrasrequests={version="^2.13",extras=["security"]}# Python specific dependencies with prereleases allowedpathlib2={version="^2.2",python="~2.7",allow-prereleases=true}# Git dependenciescleo={git="https://github.com/sdispater/cleo.git",branch="master"}# Optional dependencies (extras)pendulum={version="^1.4",optional=true}[tool.poetry.dev-dependencies]pytest="^3.0"pytest-cov="^2.4"[tool.poetry.scripts]my-script='my_package:main'There are some things we can notice here:It will try to enforcesemantic versioningas the best practice in version naming.You can specify the readme, included and excluded files: no moreMANIFEST.in.poetrywill also use VCS ignore files (like.gitignore) to populate theexcludesection.Keywords (up to 5) can be specified and will act as tags on the packaging site.The dependencies sections support caret, tilde, wildcard, inequality and multiple requirements.You must specify the python versions for which your package is compatible.poetrywill also detect if you are inside a virtualenv and install the packages accordingly.
So,poetrycan be installed globally and used everywhere.poetryalso comes with a full fledged dependency resolution library.Why?Packaging systems and dependency management in Python are rather convoluted and hard to understand for newcomers.
Even for seasoned developers it might be cumbersome at times to create all files needed in a Python project:setup.py,requirements.txt,setup.cfg,MANIFEST.inand the newly addedPipfile.So I wanted a tool that would limit everything to a single configuration file to do:
dependency management, packaging and publishing.It takes inspiration in tools that exist in other languages, likecomposer(PHP) orcargo(Rust).And, finally, there is no reliable tool to properly resolve dependencies in Python, so I startedpoetryto bring an exhaustive dependency resolver to the Python community.What about Pipenv?In short: I do not like the CLI it provides, or some of the decisions made,
and I think we can make a better and more intuitive one. Here are a few things
that I don't like.Dependency resolutionThe dependency resolution is erratic and will fail even if there is a solution. Let's take an example:pipenvinstalloslo.utils==1.4.0will fail with this error:Could not find a version that matches pbr!=0.7,!=2.1.0,<1.0,>=0.6,>=2.0.0while Poetry will get you the right set of packages:poetryaddoslo.utils=1.4.0results in :- Installing pytz (2018.3)
  - Installing netifaces (0.10.6)
  - Installing netaddr (0.7.19)
  - Installing oslo.i18n (2.1.0)
  - Installing iso8601 (0.1.12)
  - Installing six (1.11.0)
  - Installing babel (2.5.3)
  - Installing pbr (0.11.1)
  - Installing oslo.utils (1.4.0)This is possible thanks to the efficient dependency resolver at the heart of Poetry.Here is a breakdown of what exactly happens here:oslo.utils (1.4.0)depends on:pbr (>=0.6,!=0.7,<1.0)Babel (>=1.3)six (>=1.9.0)iso8601 (>=0.1.9)oslo.i18n (>=1.3.0)netaddr (>=0.7.12)netifaces (>=0.10.4)What interests us ispbr (>=0.6,!=0.7,<1.0).At this point, poetry will choosepbr==0.11.1which is the latest version that matches the constraint.Next it will try to selectoslo.i18n==3.20.0which is the latest version that matchesoslo.i18n (>=1.3.0).However this version requirespbr (!=2.1.0,>=2.0.0)which is incompatible withpbr==0.11.1,
sopoetrywill try to find a version ofoslo.i18nthat satisfiespbr (>=0.6,!=0.7,<1.0).By analyzing the releases ofoslo.i18n, it will findoslo.i18n==2.1.0which requirespbr (>=0.11,<2.0).
At this point the rest of the resolution is straightforward since there is no more conflict.Install commandWhen you specify a package to theinstallcommand it will add it as a wildcard
dependency. This means thatanyversion of this package can be installed which
can lead to compatibility issues.Also, you have to explicitly tell it to not update the locked packages when you
install new ones. This should be the default.Uninstall commandTheuninstallcommand will only remove the package specified but not its dependencies
if they are no longer needed.You either have to usesyncorcleanto fix that.Too limited in scopeFinally, thePipfileis just a replacement fromrequirements.txtand, in the end, you will still need to
populate yoursetup.pyfile (orsetup.cfg) with the exact same dependencies you declared in yourPipfile.
So, in the end, you will still need to manage a few configuration files to properly setup your project.CommandsnewThis command will help you kickstart your new Python project by creating
a directory structure suitable for most projects.poetrynewmy-packagewill create a folder as follows:my-package
├── pyproject.toml
├── README.rst
├── my_package
│   └── __init__.py
└── tests
    ├── __init__.py
    └── test_my_packageIf you want to name your project differently than the folder, you can pass
the--nameoption:poetrynewmy-folder--namemy-packageinitThis command will help you create apyproject.tomlfile interactively
by prompting you to provide basic information about your package.It will interactively ask you to fill in the fields, while using some smart defaults.poetryinitOptions--name: Name of the package.--description: Description of the package.--author: Author of the package.--dependency: Package to require with a version constraint. Should be in formatfoo:1.0.0.--dev-dependency: Development requirements, see--require.installTheinstallcommand reads thepyproject.tomlfile from the current directory, resolves the dependencies,
and installs them.poetryinstallIf there is apoetry.lockfile in the current directory,
it will use the exact versions from there instead of resolving them.
This ensures that everyone using the library will get the same versions of the dependencies.If there is nopoetry.lockfile, Poetry will create one after dependency resolution.You can specify to the command that you do not want the development dependencies installed by passing
the--no-devoption.poetryinstall--no-devYou can also specify the extras you want to be installed
by passing the-E|--extrasoption (SeeExtrasfor more info)poetryinstall--extras"mysql pgsql"poetryinstall-Emysql-EpgsqlBy defaultpoetrywill install your project's package everytime you runinstall:$poetryinstall
Installingdependenciesfromlockfile

Nodependenciestoinstallorupdate-Installing<your-package-name>(x.x.x)If you want to skip this installation, use the--no-rootoption.poetryinstall--no-rootOptions--no-dev: Do not install dev dependencies.--no-root: Do not install the root package (your project).-E|--extras: Features to install (multiple values allowed).updateIn order to get the latest versions of the dependencies and to update thepoetry.lockfile, use theupdatecommand.poetryupdateThis will resolve all dependencies of the project and write the exact versions intopoetry.lock.If you just want to update a few packages and not all, you can list them as such:poetryupdaterequeststomlOptions--dry-run: Outputs the operations but will not execute anything (implicitly enables --verbose).--no-dev: Do not install dev dependencies.--lock: Do not perform install (only update the lockfile).addTheaddcommand adds required packages to yourpyproject.tomland installs them.If you do not specify a version constraint,
poetry will choose a suitable one based on the available package versions.poetryaddrequestspendulumOptions--D|dev: Add package as development dependency.--optional: Add as an optional dependency.--dry-run: Outputs the operations but will not execute anything (implicitly enables --verbose).removeTheremovecommand removes a package from the current
list of installed packagespoetryremovependulumOptions--D|dev: Removes a package from the development dependencies.--dry-run: Outputs the operations but will not execute anything (implicitly enables --verbose).showTo list all of the available packages, you can use theshowcommand.poetryshowIf you want to see the details of a certain package, you can pass the package name.poetryshowpendulum

name:pendulum
version:1.4.2
description:Pythondatetimesmadeeasy

dependencies:-python-dateutil>=2.6.1-tzlocal>=1.4-pytzdata>=2017.2.2Options--no-dev: Do not list the dev dependencies.--tree: List the dependencies as a tree.-l|--latest: Show the latest version.-o|--outdated: Show the latest version but only for packages that are outdated.buildThebuildcommand builds the source and wheels archives.poetrybuildNote that, at the moment, only pure python wheels are supported.Options-f|--format: Limit the format to either wheel or sdist.publishThis command builds (if not already built) and publishes the package to the remote repository.It will automatically register the package before uploading if this is the first time it is submitted.poetrypublishOptions-r|--repository: The repository to register the package to (default:pypi).
Should match a repository name set by theconfigcommand.--username (-u): The username to access the repository.--password (-p): The password to access the repository.configTheconfigcommand allows you to edit poetry config settings and repositories.poetryconfig--listUsagepoetryconfig[options][setting-key][setting-value1]...[setting-valueN]setting-keyis a configuration option name andsetting-value1is a configuration value.Modifying repositoriesIn addition to modifying the config section,
the config command also supports making changes to the repositories section by using it the following way:poetryconfigrepositories.foohttps://foo.bar/simple/This will set the url for repositoryfootohttps://foo.bar/simple/.If you want to store your credentials for a specific repository, you can do so easily:poetryconfighttp-basic.foousernamepasswordIf you do not specify the password you will be prompted to write it.Options--unset: Remove the configuration element named bysetting-key.--list: Show the list of current config variables.searchThis command searches for packages on a remote index.poetrysearchrequestspendulumOptions-N|--only-name: Search only in name.lockThis command locks (without installing) the dependencies specified inpyproject.toml.poetrylockexportThis command exports the lock file to other formats.poetryexport-frequirements.txt>requirements.txtOptions--format (-f): the format to export to.  Currently, onlyrequirements.txtis supported.--output (-o): the name of the output file.  If omitted, print to standard
output.Thepyproject.tomlfileThetool.poetrysection of thepyproject.tomlfile is composed of multiple sections.nameThe name of the package.RequiredversionThe version of the package.RequiredThis should followsemantic versioning. However it will not be enforced and you remain
free to follow another specification.descriptionA short description of the package.RequiredlicenseThe license of the package.The recommended notation for the most common licenses is (alphabetical):Apache-2.0BSD-2-ClauseBSD-3-ClauseBSD-4-ClauseGPL-2.0-onlyGPL-2.0-or-laterGPL-3.0-onlyGPL-3.0-or-laterLGPL-2.1-onlyLGPL-2.1-or-laterLGPL-3.0-onlyLGPL-3.0-or-laterMITOptional, but it is highly recommended to supply this.
More identifiers are listed at theSPDX Open Source License Registry.authorsThe authors of the package.RequiredThis is a list of authors and should contain at least one author. Authors must be in the formname <email>.readmeThe readme file of the package.RequiredThe file can be eitherREADME.rstorREADME.md.homepageAn URL to the website of the project.OptionalrepositoryAn URL to the repository of the project.OptionaldocumentationAn URL to the documentation of the project.OptionalkeywordsA list of keywords (max: 5) that the package is related to.Optionalinclude and excludeA list of patterns that will be included in the final package.You can explicitly specify to Poetry that a set of globs should be ignored or included for the purposes of packaging.
The globs specified in the exclude field identify a set of files that are not included when a package is built.If a VCS is being used for a package, the exclude field will be seeded with the VCS’ ignore settings (.gitignorefor git for example).[tool.poetry]# ...include=["package/**/*.py","package/**/.c"]exclude=["package/excluded.py"]dependenciesanddev-dependenciesPoetry is configured to look for dependencies onPyPiby default.
Only the name and a version string are required in this case.[tool.poetry.dependencies]requests="^2.13.0"If you want to use a private repository, you can add it to yourpyproject.tomlfile, like so:[[tool.poetry.source]]name='private'url='http://example.com/simple'Be aware that declaring the python version for which your package
is compatible is mandatory:[tool.poetry.dependencies]python="^3.6"Caret requirementCaret requirementsallow SemVer compatible updates to a specified version.
An update is allowed if the new version number does not modify the left-most non-zero digit in the major, minor, patch grouping.
In this case, if we ranpoetry update requests, poetry would update us to version2.14.0if it was available,
but would not update us to3.0.0.
If instead we had specified the version string as^0.1.13, poetry would update to0.1.14but not0.2.0.0.0.xis not considered compatible with any other version.Here are some more examples of caret requirements and the versions that would be allowed with them:^1.2.3 := >=1.2.3 <2.0.0
^1.2 := >=1.2.0 <2.0.0
^1 := >=1.0.0 <2.0.0
^0.2.3 := >=0.2.3 <0.3.0
^0.0.3 := >=0.0.3 <0.0.4
^0.0 := >=0.0.0 <0.1.0
^0 := >=0.0.0 <1.0.0Tilde requirementsTilde requirementsspecify a minimal version with some ability to update.
If you specify a major, minor, and patch version or only a major and minor version, only patch-level changes are allowed.
If you only specify a major version, then minor- and patch-level changes are allowed.~1.2.3is an example of a tilde requirement.~1.2.3 := >=1.2.3 <1.3.0
~1.2 := >=1.2.0 <1.3.0
~1 := >=1.0.0 <2.0.0Wildcard requirementsWildcard requirementsallow for any version where the wildcard is positioned.*,1.*and1.2.*are examples of wildcard requirements.* := >=0.0.0
1.* := >=1.0.0 <2.0.0
1.2.* := >=1.2.0 <1.3.0Inequality requirementsInequality requirementsallow manually specifying a version range or an exact version to depend on.Here are some examples of inequality requirements:>= 1.2.0
> 1
< 2
!= 1.2.3Multiple requirementsMultiple version requirements can also be separated with a comma, e.g.>= 1.2, < 1.5.gitdependenciesTo depend on a library located in agitrepository,
the minimum information you need to specify is the location of the repository with the git key:[tool.poetry.dependencies]requests={git="https://github.com/requests/requests.git"}Since we haven’t specified any other information,
Poetry assumes that we intend to use the latest commit on themasterbranch to build our project.
You can combine thegitkey with therev,tag, orbranchkeys to specify something else.
Here's an example of specifying that you want to use the latest commit on a branch namednext:[tool.poetry.dependencies]requests={git="https://github.com/kennethreitz/requests.git",branch="next"}Python restricted dependenciesYou can also specify that a dependency should be installed only for specific Python versions:[tool.poetry.dependencies]pathlib2={version="^2.2",python="~2.7"}[tool.poetry.dependencies]pathlib2={version="^2.2",python=["~2.7","^3.2"]}scriptsThis section describe the scripts or executable that will be installed when installing the package[tool.poetry.scripts]poetry='poetry.console:run'After installing a package with the above toml,poetrywill be a global command available from the command line that will executeconsole.runin thepoetrypackage.extrasPoetry supports extras to allow expression of:optional dependencies, which enhance a package, but are not required; andclusters of optional dependencies.[tool.poetry]name="awesome"[tool.poetry.dependencies]# These packages are mandatory and form the core of this package’s distribution.mandatory="^1.0"# A list of all of the optional dependencies, some of which are included in the# below `extras`. They can be opted into by apps.psycopg2={version="^2.7",optional=true}mysqlclient={version="^1.3",optional=true}[tool.poetry.extras]mysql=["mysqlclient"]pgsql=["psycopg2"]When installing packages, you can specify extras by using the-E|--extrasoption:poetryinstall--extras"mysql pgsql"poetryinstall-Emysql-EpgsqlpluginsPoetry supports arbitrary plugins which work similarly tosetuptools entry points.
To match the example in the setuptools documentation, you would use the following:[tool.poetry.plugins]# Optional super table[tool.poetry.plugins."blogtool.parsers"]".rst"="some_module::SomeClass"ResourcesOfficial WebsiteIssue Tracker