A list,

Poetry is a useful package management tool in Python. In Python, the packaging system and dependency management are complex: a project often creates multiple files at the same time, for example:

  • setup.py
  • requirements.txt
  • setup.cfg
  • MANIFEST.in
  • Pipfile

For this reason, Poetry puts all of its configuration — dependency management, build, packaging, publishing — into a SINGLE TOML file for ease and convenience.

Second, the installation

Poetry requires a Python version of 2.7 or 3.5+. Poetry officials provide a script that can be quickly and easily installed.

Osx/Linux/BashonWindows installation:

curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py | python -
Copy the code

Windows PowerShell Installation:

(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -UseBasicParsing).Content | python -
Copy the code

Poetry is installed in the following locations:

  • $HOME/.local/binThe Unix system
  • %APPDATA%\Python\ScriptsWindows system

Then add the PATH to the system variable PATH, which is called using the poetry command:

poetry --version
Copy the code

Uninstall:

python install-poetry.py --uninstall
POETRY_UNINSTALL=1 python install-poetry.py
Copy the code

If you want to change the default installation path, you can set POETRY_HOME:

POETRY_HOME=/etc/poetry python install-poetry.py
Copy the code

In addition to the official installation script, you can also use pipx or PIP to install:

pipx install poetry
pipx upgrade poetry
pipx uninstall poetry
pip install --user poetry
Copy the code

Update:

poetry self update
Copy the code

Three, basic use

Perform in existing projects:

poetry init
Copy the code

This command creates a PyProject.toml file. You can manually modify the PyProject. toml file to add dependencies and then run:

poetry install
Copy the code

You can also run the add command to install a specific module and automatically add it to PyProject.toml:

$ poetry add xxxx
Copy the code

By default, poetry creates a virtual environment in {cache-dir}/virtualenvs, which you can manually modify, Or create a virtual environment in your project directory using the PyProject. toml configuration [Virtualenvs. in-project].

You can run the script in a virtual environment using the run command:

poetry run python your_script.py
Copy the code

Or simply activate your virtual environment and create a new shell to run:

poetry shell
Copy the code

Only install Dependencies:

poetry install --no-root
Copy the code

Update all locked version dependencies:

poetry update
Copy the code

4. Command options

Global options:

  • — verbose (-v | vv | VVV) : “v” normal output, “- v. v.” detail “- VVV” debug output

  • –help (-h) : Indicates help information

  • –quiet (-q) : No information is displayed

  • — ANSI: forces the ANSI output

  • –no-ansi: disables ANSI output

  • –version (-v): Displays the version

  • –no-interaction (-n): Disables interaction

NEW:

poetry new my-package
Copy the code

Create a project template with the following project structure:

My - package ├ ─ ─ pyproject. Toml ├ ─ ─ the README. Md ├ ─ ─ my_package │ └ ─ ─ just set py └ ─ ─ tests └ ─ ─ just set pyCopy the code

Init: Create the PyProject. toml file.

Install: Reads PyProject.toml and installs dependencies, which have the following options:

  • — Without: ignore dependence

  • –with: Installs optional dependencies

  • –only: only the specified dependencies are installed

  • –default: install only the default dependencies

  • –sync: Synchronize the locked version to the environment

  • –no-root: do not install the root dependency package

  • –dry-run: Outputs an operation but does not execute it

  • — Extras (-e): Install additional packages

Update: indicates the upgrade package

poetry update
Copy the code

Update all when no package is specified, you can also specify the upgrade package:

poetry update requests toml
Copy the code

It has the following options:

  • –dry-run: Outputs an operation but does not execute it

  • –no-dev: do not rely on development

  • –lock: updates are locked without installation

Add: Adds dependencies and installs them

Scope of limitation:

Poetry add "pendulum>= pendulum"Copy the code

It has the following options:

  • – group (3-d) : grouping

  • –editable (-e): Added to edit mode

  • –extras (-e): Add additional dependencies

  • –optional: Add to optional dependencies

  • –python: Specifies the Python version

  • –platform: specifies the operating system

  • –source: Install using the source name

  • — allow-PREReleases: Accepts prereleases

  • –dry-run: Outputs an operation but does not execute it

  • –lock: updates are locked without installation

**remove: ** Removes dependencies

It has the following options:

  • – group (3-d) : grouping

  • –dry-run: Outputs an operation but does not execute it

**show: ** Lists all installable packages

If you want to see information about a specific package:

Poetry show Pendulum Name: Pendulum version: 1.4.2 Description: Python datetimes made Easy Dependencies: - python-dateutil >=2.6.1 - tzlocal >=1.4 - pytzdata >=2017.2.2Copy the code

It has the following options:

  • — Without: ignore dependence

  • –with: simultaneous display

  • –only: only the specified dependencies are displayed

  • –default: displays only the default values

  • –no-dev: do not show development dependencies

  • –tree: displays in tree form

  • –latest (-l): Displays the latest version

  • –outdated (-o): Displays the latest version, but only for outdated packages

Build, build

Release the publish:

**config: ** Configuration item

Usage:

poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]
Copy the code

It has the following options:

  • –unset: Deletes the configuration item

  • –list: shows the current configuration

**run: ** Executes the command in the virtual environment

Shell: activates the virtual environment

Check: Checks the PyProject. toml file

Search: Searches for remote packets

**lock: ** Locks the version

Version: displays the version

**export: ** The locked file is exported in another format

poetry export -f requirements.txt --output requirements.txt
Copy the code

It has the following options:

  • –format (-f): Convert format. Only requirements.txt is supported for now

  • –output (-o): indicates the name of the output file

  • –dev: includes development dependencies

  • — Extras (-e): Additional dependencies

  • –without-hashes: ignore hashes

  • –with-credentials: Including qualification certificates

Env: Interacts with the virtual environment

**cache: **cache

Display cache list:

poetry cache list
Copy the code

Clear cache:

poetry cache clear pypi --all
Copy the code

**plugin: **plugin

Install plug-in:

poetry plugin add poetry-plugin
Copy the code

Display a list of plug-ins:

poetry plugin show
Copy the code

Remove plugins:

poetry plugin remove poetry-plugin
Copy the code

Source: indicates the warehouse source

Add the source:

poetry source add pypi-test https://test.pypi.org/simple/
Copy the code

Display warehouse source list:

poetry source show
Copy the code

Removed:

poetry source remove pypi-test
Copy the code

Five, configuration,

You can do this by running the config command or directly modifying the config.toml file, which is usually located in:

  • macOS: ~/Library/Application Support/pypoetry
  • Windows: C:\Users\<username>\AppData\Roaming\pypoetry
  • Unix~/.config/pypoetry

Specific items can be configured using the –local command:

poetry config virtualenvs.create false --local 
Copy the code

Configuration items:

  • Cache-dir Indicates the cache directory

  • Installer. parallel Parallel installation

  • Virtualenvs. create If it does not exist, create a virtual environment

  • Virtualen vs.in-project Creates a virtual environment in the project root directory

  • Virtualenvs. path Virtual environment path

  • Virtualenvs. Options. Always – copy copy the source file or create a link to a virtual environment

  • Virtualenvs. Options. The system – the site – packages virtual environment get the permissions system package

  • Repositories.

    Set up a new optional repository

Dependency configuration

Dependency configurations can be written in several ways:

Version restrictions:

  • Angle brackets: ^1.2 means >=1.2.0 <2.0.0

  • Tilde: ~1.2.3 means >=1.2.3 <1.3.0

  • The asterisk: 1.* means >=1.0.0 <2.0.0

Using git repositories:

[tool.poetry.dependencies]
requests = { git = "https://github.com/requests/requests.git" }
Copy the code

Using the local path:

[tool.poetry.dependencies] # directory my-package = { path = ".. /my-package/", develop = false } # file my-package = { path = ".. / my - package/dist/my - package - 0.1.0 from. Tar. Gz "}Copy the code

Use the URL:

[tool.poetry. Dependencies] # directory my-package = {url = "https://example.com/my-package-0.1.0.tar.gz"}Copy the code

Python restrictions:

[tool.poetry. Dependencies] pathlib2 = {version = "^2.2", python = "~2.7"}Copy the code

Environmental restrictions:

[tool.poetry. Dependencies] pathlib2 = {version = "^2.2", Markers = "python_version ~= '2.7' or sys_platform == 'win32'"}Copy the code

Combination:

[tool. Poetry. Dependencies] foo = [{version = "< = 1.9," python = "^ 2.7"}, {version = "^ 2.0," python = "^ 3.4"}]Copy the code

If there are too many constraints to write on one line, write on multiple lines:

[tool. Poetry. Group. Dev. Dependencies] black = {version = "19.10 b0", allow - prereleases = true, python = "^ 3.6", markers = "platform_python_implementation == 'CPython'"}Copy the code

After multiple lines:

[tool. Poetry. Group. Dev. Dependencies. Black] version = "19.10 b0" allow - prereleases = "^ 3.6" markers = = true python "platform_python_implementation == 'CPython'"Copy the code

Grouping function:

[tool. Poetry. Group. The test. The dependencies] pytest = "^" 6.0.0 pytest - mock = "*"Copy the code

For example, a composite dependency of test is established.

The following two statements are equivalent:

[tool.poetry. Dev-dependencies] pytest = "^6.0.0" pytest-mock = "*"Copy the code

Or:

[tool. Poetry. Group. Dev. Dependencies] pytest = "^" 6.0.0 pytest - mock = "*"Copy the code

Both statements declare a dev group dependency.

Declaring combinations optional is useful for specific purposes in a specific context:

[tool.poetry.group.docs]
optional = true

[tool.poetry.group.docs.dependencies]
mkdocs = "*"
Copy the code

Add a dependency to a group:

poetry add pytest --group test
Copy the code

Synchronous dependencies, using only the dependencies in poetry. Lock, and removing other dependencies that are not required:

poetry install --sync 
Copy the code

Environmental management

Poetry can be used as a standalone virtual environment for projects, rather than a system-installed one.

Switching environment:

Poetry env use /full/path/to/python poetry env use python3.7 poetry env use systemCopy the code

Displays information about the currently active environment:

poetry env info
Copy the code

The following information is displayed:

Python: 3.7.1 Implementation: CPython Path: The/path/to/poetry/cache/virtualenvs/test - O3eWbxRl - py3.7 Valid: True System Platform: Darwin OS: posix Python: /path/to/main/pythonCopy the code

List all virtual environments:

poetry env list
Copy the code

Delete environment:

Poetry env remove /full/path/to/python poetry env remove python3.7 poetry env remove 3.7 The test - O3eWbxRl - py3.7Copy the code