Package: pypoet
Poet build statusPoet helps you declare, manage and install dependencies of Python
projects, ensuring you have the right stack everywhere.The package ishighly experimentalat the moment so expect things to
change and break. However, if you feel adventurous I’d gladly appreciate
feedback and pull requests.Poet InstallInstallationpipinstallpypoetEnable tab completion for Bash, Fish, or Zshpoetsupports generating completion scripts for Bash, Fish, and Zsh.
Seepoet help completionsfor full details, but the gist is as
simple as using one of the following:# Bash$poetcompletionsbash>/etc/bash_completion.d/poet.bash-completion# Bash (macOS/Homebrew)$poetcompletionsbash>$(brew--prefix)/etc/bash_completion.d/poet.bash-completion# Fish$poetcompletionsfish>~/.config/fish/completions/poet.fish# Zsh$poetcompletionszsh>~/.zfunc/_poetNote: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:fpath+=~/.zfuncIntroductionpoetis a tool to handle dependencies installation, building and
packaging of Python packages. It only needs one file to do all of that:poetry.toml.[package]name="pypoet"version="0.1.0"description="Poet helps you declare, manage and install dependencies of Python projects, ensuring you have the right stack everywhere."license="MIT"authors=["Sébastien Eustace <sebastien@eustace.io>"]readme='README.md'repository="https://github.com/sdispater/poet"homepage="https://github.com/sdispater/poet"keywords=['packaging','poet']include=['poet/**/*','LICENSE']python=["~2.7","^3.2"][dependencies]toml="^0.9"requests="^2.13"semantic_version="^2.6"pygments="^2.2"twine="^1.8"wheel="^0.29"pip-tools="^1.8.2"cleo={git="https://github.com/sdispater/cleo.git",branch="master"}[dev-dependencies]pytest="^3.0"pytest-cov="^2.4"coverage="<4.0"httpretty="^0.8.14"[scripts]poet='poet:app.run'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.poetwill 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.poetwill also detect if you are inside a virtualenv and install the
packages accordingly. So,poetcan be installed globally and used
everywhere.Why?Packaging system and dependency management in Python is 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.in.So I wanted a tool that would limit everything to a single configuration
file to do everything: dependency management, packaging and publishing.It takes inspiration in tools that exist in other languages, likecomposer(PHP) orcargo(Rust).Note that there is no magic here,poetuses existing tools (pip,twine,setuptools,distutils,pip-tools) under the hood
to achieve that in a more intuitive way.CommandsinitThis command will help you create apoetry.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.poetinitHowever, if you just want a basic template and fill the information
directly, you can just do:poetinitdefaultOptions--name: Name of the package.--description: Description of the package.--author: Author of the package.--require: Package to require with a version constraint. Should
be in formatfoo:1.0.0.--require-dev: Development requirements, see--require.--index: Index to use when searching for packages.installTheinstallcommand reads thepoetry.tomlfile from the current
directory, resolves the dependencies, and installs them.poetinstallIf 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, Poet will create one after
dependency resolution.You can specify to the command that yo do not want the development
dependencies installed by passing the--no-devoption.poetinstall--no-devYou can also specify the features you want installed by passing the--f|--featuresoption (SeeFeaturesfor more info)poetinstall--features"mysql pgsql"poetinstall-fmysql-fpgsqlOptions--no-dev: Do not install dev dependencies.-f|--features: Features to install (multiple values allowed).--no-progress: Removes the progress display that can mess with
some terminals or scripts which don’t handle backspace characters.--index: The index to use when installing packages.updateIn order to get the latest versions of the dependencies and to update
thepoetry.lockfile, you should use theupdatecommand.poetupdateThis 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:poetupdaterequeststomlOptions--no-progress: Removes the progress display that can mess with
some terminals or scripts which don’t handle backspace characters.--index: The index to use when installing packages.packageThepackagecommand builds the source and wheels archives.Options--no-universal: Do not build a universal wheel.--no-wheels: Build only the source package.-c|--clean: Make a clean package.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.Options-r|--repository: The repository to register the package to
(default:pypi). Should match a section of your~/.pypircfile.searchThis command searches for packages on a remote index.poetsearchrequestspendulumOptions-i|--index: The index to use.-N|--only-name: Search only in name.lockThis command locks (without installing) the dependencies specified inpoetry.toml.poetlockOptions--no-progress: Removes the progress display that can mess with
some terminals or scripts which don’t handle backspace characters.-i|--index: The index to use.-f|--force: Force locking.checkThecheckcommand will check if thepoetry.tomlfile is valid.poetcheckThepoetry.tomlfileApoetry.tomlfile is composed of multiple sections.packageThis section describes the specifics of the packagenameThe 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.0GPL-2.0+GPL-3.0GPL-3.0+LGPL-2.1LGPL-2.1+LGPL-3.0LGPL-3.0+MITOptional, but it is highly recommended to supply this. More identifiers
are listed at theSPDX Open Source License
Registry.authorsThe authors of the package. This 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. If it’s a
markdown file you have to install thepandocutility so that it can be
automatically converted to a RestructuredText file.You also need to have thepypandocpackage installed.
If you installpoetviapipyou can use themarkdown-readmeextra to do so.pipinstallpypoet[markdown-readme]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.OptionalpythonA list of Python versions for which the package is compatible.Requiredinclude and excludeA list of patterns that will be included in the final package.You can explicitly specify to Poet 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).[package]# ...include=["package/**/*.py","package/**/.c"]exclude=["package/excluded.py"]If you packages lies elsewhere (say in asrcdirectory), you can
tellpoetto find them from there:include={from='src',include='**/*'}Similarly, you can tell that thesrcdirectory represent thefoopackage:include={from='src',include='**/*',as='foo'}dependenciesanddev-dependenciesPoet is configured to look for dependencies onPyPiby default. Only the name and a
version string are required in this case.[dependencies]requests="^2.13.0"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 ranpoet update requests, poet 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, poet 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:[dependencies]requests={git="https://github.com/kennethreitz/requests.git"}Since we haven’t specified any other information, Poet 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:[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:[dependencies]pathlib2={version="^2.2",python="~2.7"}[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[scripts]poet='poet:app.run'Here, we will have thepoetscript installed which will executeapp.runin thepoetpackage.featuresPoet supports features to allow expression of:optional dependencies, which enhance a package, but are not required;
andclusters of optional dependencies.[package]name="awesome"[features]mysql=["mysqlclient"]pgsql=["psycopg2"][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# above `features`. They can be opted into by apps.psycopg2={version="^2.7",optional=true}mysqlclient={version="^1.3",optional=true}When installing packages, you can specify features by using the-f|--featuresoption:poetinstall--features"mysql pgsql"poetinstall-fmysql-fpgsqlResourcesOfficial WebsiteIssue Tracker