"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "README.md" between
poetry-1.1.15.tar.gz and poetry-1.2.0.tar.gz

About: Poetry is a tool for dependency management and packaging in Python.

README.md  (poetry-1.1.15):README.md  (poetry-1.2.0)
# Poetry: Dependency Management for Python # Poetry: Dependency Management for Python
[![Tests Status](https://github.com/python-poetry/poetry/workflows/Tests/badge.s
vg?branch=master&event=push)](https://github.com/python-poetry/poetry/actions?qu
ery=workflow%3ATests+branch%3Amaster+event%3Apush)
[![Stable Version](https://img.shields.io/pypi/v/poetry?label=stable)](https://p
ypi.org/project/poetry/)
[![Pre-release Version](https://img.shields.io/github/v/release/python-poetry/po
etry?label=pre-release&include_prereleases&sort=semver)](https://pypi.org/projec
t/poetry/#history)
[![Downloads](https://img.shields.io/pypi/dm/poetry)](https://pypistats.org/pack
ages/poetry)
[![Discord](https://img.shields.io/discord/487711540787675139?logo=discord)](htt
ps://discord.com/invite/awxPgve)
Poetry helps you declare, manage and install dependencies of Python projects, Poetry helps you declare, manage and install dependencies of Python projects,
ensuring you have the right stack everywhere. ensuring you have the right stack everywhere.
![Poetry Install](https://raw.githubusercontent.com/python-poetry/poetry/master/ assets/install.gif) It requires Python 3.7+ to run.
It supports Python 2.7 and 3.5+. ![Poetry Install](https://raw.githubusercontent.com/python-poetry/poetry/master/ assets/install.gif)
**Note**: Python 2.7 and 3.5 will no longer be supported in the next feature rel ## Documentation
ease (1.2).
You should consider updating your Python version to a supported one.
[![Tests Status](https://github.com/python-poetry/poetry/workflows/Tests/badge.s
vg?branch=master&event=push)](https://github.com/python-poetry/poetry/actions?qu
ery=workflow%3ATests+branch%3Amaster+event%3Apush)
The [complete documentation](https://python-poetry.org/docs/) is available on th e [official website](https://python-poetry.org). The [complete documentation](https://python-poetry.org/docs/) is available on th e [official website](https://python-poetry.org).
## Installation ## Installation
Poetry provides a custom installer that will install `poetry` isolated Instructions on how to install `poetry` can be found [here](https://python-poetr
from the rest of your system by vendorizing its dependencies. This is the y.org/docs/master/#installation).
recommended way of installing `poetry`. You can also refer [here](https://python-poetry.org/docs/master/#enable-tab-comp
letion-for-bash-fish-or-zsh) for
*Note:* information on how to enable tab completion in your environment.
The `get-poetry.py` script described here will be replaced in Poetry 1.2 by
`install-poetry.py`.
From Poetry **1.1.7 onwards**, you can already use this script as described
[here](https://python-poetry.org/docs/master/#installation).
```bash
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poet
ry.py | python
```
Alternatively, you can download the `get-poetry.py` file and execute it separate
ly.
The setup script must be able to find one of following executables in your shell
's path environment:
- `python` (which can be a py3 or py2 interpreter)
- `python3`
- `py.exe -3` (Windows)
- `py.exe -2` (Windows)
If you want to install prerelease versions, you can do so by passing `--preview`
to `get-poetry.py`:
```bash
python get-poetry.py --preview
```
Similarly, if you want to install a specific version, you can use `--version`:
```bash
python get-poetry.py --version 0.7.0
```
Using `pip` to install `poetry` is also possible.
```bash
pip install --user poetry
```
Be aware, however, that it will also install poetry's dependencies
which might cause conflicts.
## Updating `poetry`
Updating poetry to the latest stable version is as simple as calling the `self u
pdate` command.
```bash
poetry self update
```
If you want to install prerelease versions, you can use the `--preview` option.
```bash
poetry self update --preview
```
And finally, if you want to install a specific version you can pass it as an arg
ument
to `self update`.
```bash
poetry self update 1.0.0
```
*Note:*
If you are still on poetry version < 1.0 use `poetry self:update` instead.
## Enable tab completion for Bash, Fish, or Zsh
`poetry` supports generating completion scripts for Bash, Fish, and Zsh.
See `poetry help completions` for full details, but the gist is as simple as usi
ng one of the following:
```bash
# Bash
poetry completions bash > /etc/bash_completion.d/poetry.bash-completion
# Bash (Homebrew)
poetry completions bash > $(brew --prefix)/etc/bash_completion.d/poetry.bash-com
pletion
# Fish
poetry completions fish > ~/.config/fish/completions/poetry.fish
# Fish (Homebrew)
poetry completions fish > (brew --prefix)/share/fish/vendor_completions.d/poetry
.fish
# Zsh
poetry completions zsh > ~/.zfunc/_poetry
# Zsh (Homebrew)
poetry completions zsh > $(brew --prefix)/share/zsh/site-functions/_poetry
# Zsh (Oh-My-Zsh)
mkdir $ZSH_CUSTOM/plugins/poetry
poetry completions zsh > $ZSH_CUSTOM/plugins/poetry/_poetry
# Zsh (prezto)
poetry completions zsh > ~/.zprezto/modules/completion/external/src/_poetry
```
*Note:* you may need to restart your shell in order for the changes to take
effect.
For `zsh`, you must then add the following line in your `~/.zshrc` before
`compinit` (not for homebrew setup):
```zsh
fpath+=~/.zfunc
```
## Introduction ## Introduction
`poetry` is a tool to handle dependency installation as well as building and pac kaging of Python packages. `poetry` is a tool to handle dependency installation as well as building and pac kaging of Python packages.
It only needs one file to do all of that: the new, [standardized](https://www.py thon.org/dev/peps/pep-0518/) `pyproject.toml`. It only needs one file to do all of that: the new, [standardized](https://www.py thon.org/dev/peps/pep-0518/) `pyproject.toml`.
In other words, poetry uses `pyproject.toml` to replace `setup.py`, `requirement s.txt`, `setup.cfg`, `MANIFEST.in` and the newly added `Pipfile`. In other words, poetry uses `pyproject.toml` to replace `setup.py`, `requirement s.txt`, `setup.cfg`, `MANIFEST.in` and `Pipfile`.
```toml ```toml
[tool.poetry] [tool.poetry]
name = "my-package" name = "my-package"
version = "0.1.0" version = "0.1.0"
description = "The description of the package" description = "The description of the package"
license = "MIT" license = "MIT"
authors = [ authors = [
"S├ębastien Eustace <sebastien@eustace.io>" "S├ębastien Eustace <sebastien@eustace.io>"
] ]
readme = 'README.md' # Markdown files are supported readme = "README.md"
repository = "https://github.com/python-poetry/poetry" repository = "https://github.com/python-poetry/poetry"
homepage = "https://github.com/python-poetry/poetry" homepage = "https://python-poetry.org"
keywords = ['packaging', 'poetry'] keywords = ["packaging", "poetry"]
[tool.poetry.dependencies] [tool.poetry.dependencies]
python = "~2.7 || ^3.2" # Compatible python versions must be declared here python = "^3.8" # Compatible python versions must be declared here
toml = "^0.9" aiohttp = "^3.8.1"
# Dependencies with extras # Dependencies with extras
requests = { version = "^2.13", extras = [ "security" ] } requests = { version = "^2.28", extras = [ "security" ] }
# Python specific dependencies with prereleases allowed # Python specific dependencies with prereleases allowed
pathlib2 = { version = "^2.2", python = "~2.7", allow-prereleases = true } tomli = { version = "^2.0.1", python = "<3.11", allow-prereleases = true }
# Git dependencies # Git dependencies
cleo = { git = "https://github.com/sdispater/cleo.git", branch = "master" } cleo = { git = "https://github.com/python-poetry/cleo.git", branch = "master" }
# Optional dependencies (extras) # Optional dependencies (extras)
pendulum = { version = "^1.4", optional = true } pendulum = { version = "^2.1.2", optional = true }
[tool.poetry.dev-dependencies] [tool.poetry.dev-dependencies]
pytest = "^3.0" pytest = "^7.1.2"
pytest-cov = "^2.4" pytest-cov = "^3.0"
[tool.poetry.scripts] [tool.poetry.scripts]
my-script = 'my_package:main' my-script = "my_package:main"
``` ```
There are some things we can notice here: There are some things we can notice here:
* It will try to enforce [semantic versioning](<http://semver.org>) as the best practice in version naming. * It will try to enforce [semantic versioning](<http://semver.org>) as the best practice in version naming.
* You can specify the readme, included and excluded files: no more `MANIFEST.in` . * You can specify the readme, included and excluded files: no more `MANIFEST.in` .
`poetry` will also use VCS ignore files (like `.gitignore`) to populate the `exc lude` section. `poetry` will also use VCS ignore files (like `.gitignore`) to populate the `exc lude` section.
* Keywords (up to 5) can be specified and will act as tags on the packaging site . * Keywords can be specified and will act as tags on the packaging site.
* The dependencies sections support caret, tilde, wildcard, inequality and multi ple requirements. * The dependencies sections support caret, tilde, wildcard, inequality and multi ple requirements.
* You must specify the python versions for which your package is compatible. * You must specify the python versions for which your package is compatible.
`poetry` will also detect if you are inside a virtualenv and install the package s accordingly. `poetry` will also detect if you are inside a virtualenv and install the package s accordingly.
So, `poetry` can be installed globally and used everywhere. So, `poetry` can be installed globally and used everywhere.
`poetry` also comes with a full fledged dependency resolution library. `poetry` also comes with a full fledged dependency resolution library.
## Why? ## Why?
Packaging systems and dependency management in Python are rather convoluted and hard to understand for newcomers. 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`, 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` and the newly added `Pipfile`. `requirements.txt`, `setup.cfg`, `MANIFEST.in` and `Pipfile`.
So I wanted a tool that would limit everything to a single configuration file to do: So I wanted a tool that would limit everything to a single configuration file to do:
dependency management, packaging and publishing. dependency management, packaging and publishing.
It takes inspiration in tools that exist in other languages, like `composer` (PH P) or `cargo` (Rust). It takes inspiration in tools that exist in other languages, like `composer` (PH P) or `cargo` (Rust).
And, finally, there is no reliable tool to properly resolve dependencies in Pyth And, finally, I started `poetry` to bring another exhaustive dependency resolver
on, so I started `poetry` to the Python community apart from
to bring an exhaustive dependency resolver to the Python community. [Conda's](https://conda.io).
### 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 resolution
The dependency resolution is erratic and will fail even if there is a solution.
Let's take an example:
```bash
pipenv install oslo.utils==1.4.0
```
will fail with this error:
```text
Could not find a version that matches pbr!=0.7,!=2.1.0,<1.0,>=0.6,>=2.0.0
```
while Poetry will get you the right set of packages:
```bash
poetry add oslo.utils=1.4.0
```
results in :
```text
- 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 Poe
try.
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 is `pbr (>=0.6,!=0.7,<1.0)`.
At this point, poetry will choose `pbr==0.11.1` which is the latest version that
matches the constraint.
Next it will try to select `oslo.i18n==3.20.0` which is the latest version that
matches `oslo.i18n (>=1.3.0)`.
However this version requires `pbr (!=2.1.0,>=2.0.0)` which is incompatible with
`pbr==0.11.1`,
so `poetry` will try to find a version of `oslo.i18n` that satisfies `pbr (>=0.6
,!=0.7,<1.0)`.
By analyzing the releases of `oslo.i18n`, it will find `oslo.i18n==2.1.0` which
requires `pbr (>=0.11,<2.0)`.
At this point the rest of the resolution is straightforward since there is no mo
re conflict.
## Resources ## Resources
* [Official Website](https://python-poetry.org) * [Official Website](https://python-poetry.org)
* [Issue Tracker](https://github.com/python-poetry/poetry/issues) * [Issue Tracker](https://github.com/python-poetry/poetry/issues)
* [Discord](https://discordapp.com/invite/awxPgve) * [Discord](https://discord.com/invite/awxPgve)
 End of changes. 20 change blocks. 
220 lines changed or deleted 39 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)