Skip to content

P
python-poetry
Commit d24dab0a by Sébastien Eustace Committed by GitHub
Options

Improve documentation (#1716)

parent 71a92be0
Showing with 163 additions and 951 deletions
README.md
...@@ -9,6 +9,8 @@ It supports Python 2.7 and 3.4+. ...@@ -9,6 +9,8 @@ It supports Python 2.7 and 3.4+.
![Tests Status](https://github.com/python-poetry/poetry/workflows/Tests/badge.svg) ![Tests Status](https://github.com/python-poetry/poetry/workflows/Tests/badge.svg)
The [complete documentation](https://python-poetry.org/docs/) is available on the [official website](https://python-poetry.org).
## Installation ## Installation
Poetry provides a custom installer that will install `poetry` isolated Poetry provides a custom installer that will install `poetry` isolated
...@@ -60,7 +62,7 @@ And finally, if you want to install a specific version you can pass it as an arg ...@@ -60,7 +62,7 @@ And finally, if you want to install a specific version you can pass it as an arg
to `self update`. to `self update`.
```bash ```bash
poetry self update 0.8.0 poetry self update 1.0.0
``` ```
!!!note !!!note
...@@ -242,597 +244,6 @@ so `poetry` will try to find a version of `oslo.i18n` that satisfies `pbr (>=0.6 ...@@ -242,597 +244,6 @@ so `poetry` will try to find a version of `oslo.i18n` that satisfies `pbr (>=0.6
By analyzing the releases of `oslo.i18n`, it will find `oslo.i18n==2.1.0` which requires `pbr (>=0.11,<2.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 more conflict. At this point the rest of the resolution is straightforward since there is no more conflict.
#### Install command
When you specify a package to the `install` command it will add it as a wildcard
dependency. This means that **any** version 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 command
The `uninstall` command will only remove the package specified but not its dependencies
if they are no longer needed.
You either have to use `sync` or `clean` to fix that.
#### Too limited in scope
Finally, the `Pipfile` is just a replacement from `requirements.txt` and, in the end, you will still need to
populate your `setup.py` file (or `setup.cfg`) with the exact same dependencies you declared in your `Pipfile`.
So, in the end, you will still need to manage a few configuration files to properly setup your project.
## Commands
### new
This command will help you kickstart your new Python project by creating
a directory structure suitable for most projects.
```bash
poetry new my-package
```
will create a folder as follows:
```text
my-package
├── pyproject.toml
├── README.rst
├── my_package
│ └── __init__.py
└── tests
├── __init__.py
└── test_my_package
```
If you want to name your project differently than the folder, you can pass
the `--name` option:
```bash
poetry new my-folder --name my-package
```
### init
This command will help you create a `pyproject.toml` file 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.
```bash
poetry init
```
#### Options
* `--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 format `foo:1.0.0`.
* `--dev-dependency`: Development requirements, see `--require`.
### install
The `install` command reads the `pyproject.toml` file from the current directory, resolves the dependencies,
and installs them.
```bash
poetry install
```
If there is a `poetry.lock` file 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 no `poetry.lock` file, 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-dev` option.
```bash
poetry install --no-dev
```
You can also specify the extras you want to be installed
by passing the `-E|--extras` option (See [Extras](#extras) for more info)
```bash
poetry install --extras "mysql pgsql"
poetry install -E mysql -E pgsql
```
By default `poetry` will install your project's package everytime you run `install`:
```bash
$ poetry install
Installing dependencies from lock file
No dependencies to install or update
- Installing <your-package-name> (x.x.x)
```
If you want to skip this installation, use the `--no-root` option.
```bash
poetry install --no-root
```
#### Options
* `--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).
### update
In order to get the latest versions of the dependencies and to update the `poetry.lock` file, use the `update` command.
```bash
poetry update
```
This will resolve all dependencies of the project and write the exact versions into `poetry.lock`.
If you just want to update a few packages and not all, you can list them as such:
```bash
poetry update requests toml
```
#### Options
* `--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).
### add
The `add` command adds required packages to your `pyproject.toml` and installs them.
If you do not specify a version constraint,
poetry will choose a suitable one based on the available package versions.
```bash
poetry add requests pendulum
```
#### Options
* `--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).
### remove
The `remove` command removes a package from the current
list of installed packages
```bash
poetry remove pendulum
```
#### Options
* `--D|dev`: Removes a package from the development dependencies.
* `--dry-run` : Outputs the operations but will not execute anything (implicitly enables --verbose).
### show
To list all of the available packages, you can use the `show` command.
```bash
poetry show
```
If you want to see the details of a certain package, you can pass the package name.
```bash
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.2
```
#### Options
* `--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.
### build
The `build` command builds the source and wheels archives.
```bash
poetry build
```
Note that, at the moment, only pure python wheels are supported.
#### Options
* `-f|--format`: Limit the format to either wheel or sdist.
### publish
This 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.
```bash
poetry publish
```
#### Options
* `-r|--repository`: The repository to register the package to (default: `pypi`).
Should match a repository name set by the [`config`](#config) command.
* `--username (-u)`: The username to access the repository.
* `--password (-p)`: The password to access the repository.
### `config`
The `config` command allows you to edit poetry config settings and repositories.
```bash
poetry config --list
```
#### Usage
````bash
poetry config [options] [setting-key] [setting-value1] ... [setting-valueN]
````
`setting-key` is a configuration option name and `setting-value1` is a configuration value.
#### Modifying repositories
In addition to modifying the config section,
the config command also supports making changes to the repositories section by using it the following way:
```bash
poetry config repositories.foo https://foo.bar/simple/
```
This will set the url for repository `foo` to `https://foo.bar/simple/`.
If you want to store your credentials for a specific repository, you can do so easily:
```bash
poetry config http-basic.foo username password
```
If you do not specify the password you will be prompted to write it.
#### Options
* `--unset`: Remove the configuration element named by `setting-key`.
* `--list`: Show the list of current config variables.
### search
This command searches for packages on a remote index.
```bash
poetry search requests pendulum
```
#### Options
* `-N|--only-name`: Search only in name.
### lock
This command locks (without installing) the dependencies specified in `pyproject.toml`.
```bash
poetry lock
```
### export
This command exports the lock file to other formats.
```bash
poetry export -f requirements.txt > requirements.txt
```
#### Options
* `--format (-f)`: the format to export to. Currently, only
`requirements.txt` is supported.
* `--output (-o)`: the name of the output file. If omitted, print to standard
output.
## The `pyproject.toml` file
The `tool.poetry` section of the `pyproject.toml` file is composed of multiple sections.
#### name
The name of the package. **Required**
#### version
The version of the package. **Required**
This should follow [semantic versioning](http://semver.org/). However it will not be enforced and you remain
free to follow another specification.
#### description
A short description of the package. **Required**
#### license
The license of the package.
The recommended notation for the most common licenses is (alphabetical):
* Apache-2.0
* BSD-2-Clause
* BSD-3-Clause
* BSD-4-Clause
* GPL-2.0-only
* GPL-2.0-or-later
* GPL-3.0-only
* GPL-3.0-or-later
* LGPL-2.1-only
* LGPL-2.1-or-later
* LGPL-3.0-only
* LGPL-3.0-or-later
* MIT
Optional, but it is highly recommended to supply this.
More identifiers are listed at the [SPDX Open Source License Registry](https://www.spdx.org/licenses/).
#### authors
The authors of the package. **Required**
This is a list of authors and should contain at least one author. Authors must be in the form `name <email>`.
#### readme
The readme file of the package. **Required**
The file can be either `README.rst` or `README.md`.
#### homepage
An URL to the website of the project. **Optional**
#### repository
An URL to the repository of the project. **Optional**
#### documentation
An URL to the documentation of the project. **Optional**
#### keywords
A list of keywords (max: 5) that the package is related to. **Optional**
#### include and exclude
A 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 (`.gitignore` for git for example).
```toml
[tool.poetry]
# ...
include = ["package/**/*.py", "package/**/.c"]
```
```toml
exclude = ["package/excluded.py"]
```
### `dependencies` and `dev-dependencies`
Poetry is configured to look for dependencies on [PyPi](https://pypi.org) by default.
Only the name and a version string are required in this case.
```toml
[tool.poetry.dependencies]
requests = "^2.13.0"
```
If you want to use a private repository, you can add it to your `pyproject.toml` file, like so:
```toml
[[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:
```toml
[tool.poetry.dependencies]
python = "^3.6"
```
#### Caret requirement
**Caret requirements** allow 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 ran `poetry update requests`, poetry would update us to version `2.14.0` if it was available,
but would not update us to `3.0.0`.
If instead we had specified the version string as `^0.1.13`, poetry would update to `0.1.14` but not `0.2.0`.
`0.0.x` is not considered compatible with any other version.
Here are some more examples of caret requirements and the versions that would be allowed with them:
```text
^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.0
```
#### Tilde requirements
**Tilde requirements** specify 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.3` is an example of a tilde requirement.
```text
~1.2.3 := >=1.2.3 <1.3.0
~1.2 := >=1.2.0 <1.3.0
~1 := >=1.0.0 <2.0.0
```
#### Wildcard requirements
**Wildcard requirements** allow for any version where the wildcard is positioned.
`*`, `1.*` and `1.2.*` are examples of wildcard requirements.
```text
* := >=0.0.0
1.* := >=1.0.0 <2.0.0
1.2.* := >=1.2.0 <1.3.0
```
#### Inequality requirements
**Inequality requirements** allow manually specifying a version range or an exact version to depend on.
Here are some examples of inequality requirements:
```text
>= 1.2.0
> 1
< 2
!= 1.2.3
```
#### Multiple requirements
Multiple version requirements can also be separated with a comma, e.g. `>= 1.2, < 1.5`.
#### `git` dependencies
To depend on a library located in a `git` repository,
the minimum information you need to specify is the location of the repository with the git key:
```toml
[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 the `master` branch to build our project.
You can combine the `git` key with the `rev`, `tag`, or `branch` keys to specify something else.
Here's an example of specifying that you want to use the latest commit on a branch named `next`:
```toml
[tool.poetry.dependencies]
requests = { git = "https://github.com/kennethreitz/requests.git", branch = "next" }
```
#### Python restricted dependencies
You can also specify that a dependency should be installed only for specific Python versions:
```toml
[tool.poetry.dependencies]
pathlib2 = { version = "^2.2", python = "~2.7" }
```
```toml
[tool.poetry.dependencies]
pathlib2 = { version = "^2.2", python = ["~2.7", "^3.2"] }
```
### `scripts`
This section describe the scripts or executable that will be installed when installing the package
```toml
[tool.poetry.scripts]
poetry = 'poetry.console:run'
```
After installing a package with the above toml, `poetry` will be a global command available from the command line that will execute `console.run` in the `poetry` package.
### `extras`
Poetry supports extras to allow expression of:
* optional dependencies, which enhance a package, but are not required; and
* clusters of optional dependencies.
```toml
[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|--extras` option:
```bash
poetry install --extras "mysql pgsql"
poetry install -E mysql -E pgsql
```
### `plugins`
Poetry supports arbitrary plugins which work similarly to
[setuptools entry points](http://setuptools.readthedocs.io/en/latest/setuptools.html).
To match the example in the setuptools documentation, you would use the following:
```toml
[tool.poetry.plugins] # Optional super table
[tool.poetry.plugins."blogtool.parsers"]
".rst" = "some_module::SomeClass"
```
## Resources ## Resources
* [Official Website](https://python-poetry.org) * [Official Website](https://python-poetry.org)
......
docs/docs/basic-usage.md
...@@ -69,7 +69,8 @@ It will automatically find a suitable version constraint **and install** the pac ...@@ -69,7 +69,8 @@ It will automatically find a suitable version constraint **and install** the pac
In our example, we are requesting the `pendulum` package with the version constraint `^1.4`. In our example, we are requesting the `pendulum` package with the version constraint `^1.4`.
This means any version greater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`). This means any version greater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <2.0.0`).
Please read [versions](/docs/versions/) for more in-depth information on versions, how versions relate to each other, and on version constraints. Please read [Dependency specification](/docs/dependency-specification) for more in-depth information on versions,
how versions relate to each other, and on the different ways you can specify dependencies.
!!!note !!!note
...@@ -147,107 +148,3 @@ and update the lock file with the new versions. ...@@ -147,107 +148,3 @@ and update the lock file with the new versions.
Poetry will display a **Warning** when executing an install command if `poetry.lock` and `pyproject.toml` Poetry will display a **Warning** when executing an install command if `poetry.lock` and `pyproject.toml`
are not synchronized. are not synchronized.
## Poetry and virtualenvs
When you execute the `install` command (or any other "install" commands like `add` or `remove`),
Poetry will check if it's currently inside a virtualenv and, if not, will use an existing one
or create a brand new one for you to always work isolated from your global Python installation.
By default, Poetry will use the currently activated Python version
to create the virtualenv for the current project.
To easily switch between Python versions, it is recommended to
use [pyenv](https://github.com/pyenv/pyenv) or similar tools.
For instance, if your project is Python 2.7 only, a standard workflow
would be:
```bash
pyenv install 2.7.15
pyenv local 2.7.15 # Activate Python 2.7 for the current project
poetry install
```
However, this might not be feasible for your system, especially Windows where `pyenv`,
is not available. To circumvent that you can use the `env use` command to tell
Poetry which Python version to use for the current project.
```bash
poetry env use /full/path/to/python
```
If you have the python executable in your `PATH` you can use it:
```bash
poetry env use python3.7
```
You can even just use the minor Python version in this case:
```bash
poetry env use 3.7
```
If you want to disable the explicitly activated virtualenv, you can use the
special `system` Python version to retrieve the default behavior:
```bash
poetry env use system
```
If you want to get basic information about the currently activated virtualenv,
you can use the `env info` command:
```bash
poetry env info
```
will output something similar to this:
```text
Virtualenv
Python: 3.7.1
Implementation: CPython
Path: /path/to/poetry/cache/virtualenvs/test-O3eWbxRl-py3.7
Valid: True
System
Platform: darwin
OS: posix
Python: /path/to/main/python
```
If you only want to know the path to the virtualenv, you can pass the `--path` option
to `env info`:
```bash
poetry env info --path
```
You can also list all the virtualenvs associated with the current virtualenv
with the `env list` command:
```bash
poetry env list
```
will output something like the following:
```text
test-O3eWbxRl-py2.7
test-O3eWbxRl-py3.6
test-O3eWbxRl-py3.7 (Activated)
```
Finally, you can delete existing virtualenvs by using `env remove`:
```bash
poetry env remove /full/path/to/python
poetry env remove python3.7
poetry env remove 3.7
poetry env remove test-O3eWbxRl-py3.7
```
If your remove the currently activated virtualenv, it will be automatically deactivated.
docs/docs/cli.md
...@@ -451,106 +451,4 @@ poetry export -f requirements.txt > requirements.txt ...@@ -451,106 +451,4 @@ poetry export -f requirements.txt > requirements.txt
The `env` command regroups sub commands to interact with the virtualenvs The `env` command regroups sub commands to interact with the virtualenvs
associated with a specific project. associated with a specific project.
### env use See [Managing environments](./managing-environments.md) for more information about these commands.
The `env use` command tells Poetry which Python version
to use for the current project.
```bash
poetry env use /full/path/to/python
```
If you have the python executable in your `PATH` you can use it:
```bash
poetry env use python3.7
```
You can even just use the minor Python version in this case:
```bash
poetry env use 3.7
```
If you want to disable the explicitly activated virtualenv, you can use the
special `system` Python version to retrieve the default behavior:
```bash
poetry env use system
```
### env info
The `env info` command displays basic information about the currently activated virtualenv:
```bash
poetry env info
```
will output something similar to this:
```text
Virtualenv
Python: 3.7.1
Implementation: CPython
Path: /path/to/poetry/cache/virtualenvs/test-O3eWbxRl-py3.7
Valid: True
System
Platform: darwin
OS: posix
Python: /path/to/main/python
```
If you only want to know the path to the virtualenv, you can pass the `--path` option
to `env info`:
```bash
poetry env info --path
```
#### Options
* `--path`: Only display the path of the virtualenv.
### env list
The `env list` command lists all the virtualenvs associated with the current virtualenv.
```bash
poetry env list
```
will output something like the following:
```text
test-O3eWbxRl-py2.7
test-O3eWbxRl-py3.6
test-O3eWbxRl-py3.7 (Activated)
```
#### Options
* `--full-path`: Display the full path of the virtualenvs.
### env remove
The `env remove` command deletes virtualenvs associated with the current project:
```bash
poetry env remove /full/path/to/python
```
Similarly to `env use`, you can either pass `python3.7`, `3.7` or the name of
the virtualenv (as returned by `env list`):
```bash
poetry env remove python3.7
poetry env remove 3.7
poetry env remove test-O3eWbxRl-py3.7
```
!!!note
If your remove the currently activated virtualenv, it will be automatically deactivated.
docs/docs/configuration.md
...@@ -104,7 +104,7 @@ Defaults to one of the following directories: ...@@ -104,7 +104,7 @@ Defaults to one of the following directories:
### `virtualenvs.create`: boolean ### `virtualenvs.create`: boolean
Create a new virtualenv if one doesn't already exist. Create a new virtual environment if one doesn't already exist.
Defaults to `true`. Defaults to `true`.
### `virtualenvs.in-project`: boolean ### `virtualenvs.in-project`: boolean
...@@ -114,7 +114,7 @@ Defaults to `false`. ...@@ -114,7 +114,7 @@ Defaults to `false`.
### `virtualenvs.path`: string ### `virtualenvs.path`: string
Directory where virtualenvs will be created. Directory where virtual environments will be created.
Defaults to `{cache-dir}/virtualenvs` (`{cache-dir}\virtualenvs` on Windows). Defaults to `{cache-dir}/virtualenvs` (`{cache-dir}\virtualenvs` on Windows).
### `repositories.<name>`: string ### `repositories.<name>`: string
......
docs/docs/contributing.md
# Contributing to Poetry {!../CONTRIBUTING.md!}
First off, thank for taking the time to contribute!
The following is a set of guidelines for contributing to Poetry on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
#### Table of Contents
[How to contribute](#how-to-contribute)
* [Reporting bugs](#reporting-bugs)
* [Suggesting enhancements](#suggesting-enhancements)
* [Contributing to code](#contributing-to-code)
## How to contribute
### Reporting bugs
This section guides you through submitting a bug report for Poetry.
Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports.
Before creating bug reports, please check [this list](#before-submitting-a-bug-report) to be sure that you need to create one. When you are creating a bug report, please include as many details as possible. Fill out the [required template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/1_Bug_report.md), the information it asks helps the maintainers resolve the issue faster.
!!!note
If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one.
#### Before submitting a bug report
* **Check the [FAQs on the official website](https://python-poetry.org)** for a list of common questions and problems.
* **Check that your issue does not already exist in the [issue tracker](https://github.com/python-poetry/poetry/issues)**.
#### How do I submit a bug report
Bugs are tracked on the [official issue tracker](https://github.com/python-poetry/poetry/issues) where you can create a new one and provide the following information by filling in [the template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/1_Bug_report.md).
Explain the problem and include additional details to help maintainers reproduce the problem:
* **Use a clear and descriptive title** for the issue to identify the problem.
* **Describe the exact steps which reproduce the problem** in as many details as possible.
* **Provide your pyproject.toml file** in a [Gist](https://gist.github.com) after removing potential private information (like private package repositories).
* **Provide specific examples to demonstrate the steps to reproduce the issue**. Include links to files or GitHub projects, or copy/pasteable snippets, which you use in those examples.
* **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior.
* **Explain which behavior you expected to see instead and why.**
* **If the problem is an unexpected error being raised**, execute the corresponding command in **debug** mode (the `-vvv` option).
Provide more context by answering these questions:
* **Did the problem start happening recently** (e.g. after updating to a new version of Poetry) or was this always a problem?
* If the problem started happening recently, **can you reproduce the problem in an older version of Poetry?** What's the most recent version in which the problem doesn't happen?
* **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens.
Include details about your configuration and environment:
* **Which version of Poetry are you using?** You can get the exact version by running `poetry -V` in your terminal.
* **Which Python version Poetry has been installed for?** Execute the `debug:info` to get the information.
* **What's the name and version of the OS you're using**?
### Suggesting enhancements
This section guides you through submitting an enhancement suggestion for Poetry, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion and find related suggestions.
Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-an-enhancement-suggestion). Fill in [the template](https://github.com/python-poetry/poetry/blob/master/.github/ISSUE_TEMPLATE/2_Feature_request.md), including the steps that you imagine you would take if the feature you're requesting existed.
#### Before submitting an enhancement suggestion
* **Check the [FAQs on the official website](https://python-poetry.org)** for a list of common questions and problems.
* **Check that your issue does not already exist in the [issue tracker](https://github.com/python-poetry/poetry/issues)**.
#### How do I submit an enhancement suggestion?
Enhancement suggestions are tracked on the [official issue tracker](https://github.com/python-poetry/poetry/issues) where you can create a new one and provide the following information:
* **Use a clear and descriptive title** for the issue to identify the suggestion.
* **Provide a step-by-step description of the suggested enhancement** in as many details as possible.
* **Provide specific examples to demonstrate the steps**..
* **Describe the current behavior** and **explain which behavior you expected to see instead** and why.
### Contributing to code
#### Local development
You will need Poetry to start contributing on the Poetry codebase. Refer to the [documentation](https://python-poetry.org/docs/#introduction) to start using Poetry.
You will first need to clone the repository using `git` and place yourself in its directory:
```bash
$ git clone git@github.com:sdispater/poetry.git
$ cd poetry
```
Now, you will need to install the required dependency for Poetry and be sure that the current
tests are passing on your machine:
```bash
$ poetry install
$ poetry run pytest tests/
```
Poetry uses the [black](https://github.com/ambv/black) coding style and you must ensure that your
code follows it. If not, the CI will fail and your Pull Request will not be merged.
Similarly, the import statements are sorted with [isort](https://github.com/timothycrosley/isort)
and special care must be taken to respect it. If you don't, the CI will fail as well.
To make sure that you don't accidentally commit code that does not follow the coding style, you can
install a pre-commit hook that will check that everything is in order:
```bash
$ poetry run pre-commit install
```
You can also run it anytime using:
```bash
$ poetry run pre-commit run --all-files
```
Your code must always be accompanied by corresponding tests, if tests are not present your code
will not be merged.
#### Pull requests
* Fill in [the required template](https://github.com/python-poetry/poetry/blob/master/.github/PULL_REQUEST_TEMPLATE.md)
* Be sure that you pull request contains tests that cover the changed or added code.
* If you changes warrant a documentation change, the pull request must also update the documentation.
docs/docs/versions.md → docs/docs/dependency-specification.md
# Versions and constraints # Dependency specification
Poetry recommends following [semantic versioning](https://semver.org) but will not enforce it. Dependencies for a project can be specified in various forms, which depend on the type
of the dependency and on the optional constraints that might be needed for it to be installed.
## Version constraints ## Version constraints
...@@ -74,7 +75,7 @@ If other dependencies require a different version, the solver will ultimately fa ...@@ -74,7 +75,7 @@ If other dependencies require a different version, the solver will ultimately fa
Multiple version requirements can also be separated with a comma, e.g. `>= 1.2, < 1.5`. Multiple version requirements can also be separated with a comma, e.g. `>= 1.2, < 1.5`.
### `git` dependencies ## `git` dependencies
To depend on a library located in a `git` repository, To depend on a library located in a `git` repository,
the minimum information you need to specify is the location of the repository with the git key: the minimum information you need to specify is the location of the repository with the git key:
...@@ -94,7 +95,7 @@ Here's an example of specifying that you want to use the latest commit on a bran ...@@ -94,7 +95,7 @@ Here's an example of specifying that you want to use the latest commit on a bran
requests = { git = "https://github.com/kennethreitz/requests.git", branch = "next" } requests = { git = "https://github.com/kennethreitz/requests.git", branch = "next" }
``` ```
### `path` dependencies ## `path` dependencies
To depend on a library located in a local directory or file, To depend on a library located in a local directory or file,
you can use the `path` property: you can use the `path` property:
...@@ -109,7 +110,7 @@ my-package = { path = "../my-package/dist/my-package-0.1.0.tar.gz" } ...@@ -109,7 +110,7 @@ my-package = { path = "../my-package/dist/my-package-0.1.0.tar.gz" }
``` ```
### `url` dependencies ## `url` dependencies
To depend on a library located on a remote archive, To depend on a library located on a remote archive,
you can use the `url` property: you can use the `url` property:
...@@ -127,7 +128,7 @@ poetry add https://example.com/my-package-0.1.0.tar.gz ...@@ -127,7 +128,7 @@ poetry add https://example.com/my-package-0.1.0.tar.gz
``` ```
### Python restricted dependencies ## Python restricted dependencies
You can also specify that a dependency should be installed only for specific Python versions: You can also specify that a dependency should be installed only for specific Python versions:
...@@ -141,7 +142,7 @@ pathlib2 = { version = "^2.2", python = "~2.7" } ...@@ -141,7 +142,7 @@ pathlib2 = { version = "^2.2", python = "~2.7" }
pathlib2 = { version = "^2.2", python = "~2.7 || ^3.2" } pathlib2 = { version = "^2.2", python = "~2.7 || ^3.2" }
``` ```
### Using environment markers ## Using environment markers
If you need more complex install conditions for your dependencies, If you need more complex install conditions for your dependencies,
Poetry supports [environment markers](https://www.python.org/dev/peps/pep-0508/#environment-markers) Poetry supports [environment markers](https://www.python.org/dev/peps/pep-0508/#environment-markers)
...@@ -153,7 +154,7 @@ pathlib2 = { version = "^2.2", markers = "python_version ~= '2.7' or sys_platfor ...@@ -153,7 +154,7 @@ pathlib2 = { version = "^2.2", markers = "python_version ~= '2.7' or sys_platfor
``` ```
### Multiple constraints dependencies ## Multiple constraints dependencies
Sometimes, one of your dependency may have different version ranges depending Sometimes, one of your dependency may have different version ranges depending
on the target Python versions. on the target Python versions.
......
docs/docs/faq.md
...@@ -60,14 +60,14 @@ commands = ...@@ -60,14 +60,14 @@ commands =
poetry run pytest tests/ poetry run pytest tests/
``` ```
## I don't want Poetry to manage my virtualenvs. Can I disable it? ## I don't want Poetry to manage my virtual environments. Can I disable it?
While Poetry automatically creates virtualenvs to always work isolated While Poetry automatically creates virtual environments to always work isolated
from the global Python installation, there are valid reasons why it's not necessary from the global Python installation, there are valid reasons why it's not necessary
and is an overhead, like when working with containers. and is an overhead, like when working with containers.
In this case, you can disable this feature by setting the `virtualenvs.create` setting to `false`: In this case, you can disable this feature by setting the `virtualenvs.create` setting to `false`:
```bash ```bash
poetry config settings.virtualenvs.create false poetry config virtualenvs.create false
``` ```
docs/docs/libraries.md
...@@ -2,11 +2,6 @@ ...@@ -2,11 +2,6 @@
This chapter will tell you how to make your library installable through Poetry. This chapter will tell you how to make your library installable through Poetry.
## Every project is a package
As soon as you have a `pyproject.toml` in a directory, that directory is a package.
However, to make it accessible to others you will need to package and publish it.
## Versioning ## Versioning
...@@ -14,7 +9,7 @@ While Poetry does not enforce any convention regarding package versioning, ...@@ -14,7 +9,7 @@ While Poetry does not enforce any convention regarding package versioning,
it **strongly** recommends to follow [semantic versioning](https://semver.org). it **strongly** recommends to follow [semantic versioning](https://semver.org).
This has many advantages for the end users and allows them to set appropriate This has many advantages for the end users and allows them to set appropriate
[version constraints](/docs/versions/). [version constraints](/docs/dependency-specification/#version-constraints).
## Lock file ## Lock file
......
docs/docs/managing-environments.md 0 → 100644
# Managing environments
Poetry makes project environment isolation one of its core feature.
What this means is that it will always work isolated from your global Python installation.
To achieve this, it will first check if it's currently running inside a virtual environment.
If it is, it will use it directly without creating a new one. But if it's not, it will use
one that it has already created or create a brand new one for you.
By default, Poetry will try to use the currently activated Python version
to create the virtual environment for the current project.
However, for various reasons, this Python version might not be compatible
with the `python` requirement of the project. In this case, Poetry will try
to find one that is and use it. If it's unable to do so then you will be prompted
to activate one explicitly, see [Switching environments](#switching-between-environments).
!!!note
To easily switch between Python versions, it is recommended to
use [pyenv](https://github.com/pyenv/pyenv) or similar tools.
For instance, if your project is Python 2.7 only, a standard workflow
would be:
```bash
pyenv install 2.7.15
pyenv local 2.7.15 # Activate Python 2.7 for the current project
poetry install
```
## Switching between environments
Sometimes this might not be feasible for your system, especially Windows where `pyenv`
is not available, or you simply prefer to have a more explicit control over your environment.
For this specific purpose, you can use the `env use` command to tell Poetry
which Python version to use for the current project.
```bash
poetry env use /full/path/to/python
```
If you have the python executable in your `PATH` you can use it:
```bash
poetry env use python3.7
```
You can even just use the minor Python version in this case:
```bash
poetry env use 3.7
```
If you want to disable the explicitly activated virtual environment, you can use the
special `system` Python version to retrieve the default behavior:
```bash
poetry env use system
```
## Displaying the environment information
If you want to get basic information about the currently activated virtual environment,
you can use the `env info` command:
```bash
poetry env info
```
will output something similar to this:
```text
Virtual environment
Python: 3.7.1
Implementation: CPython
Path: /path/to/poetry/cache/virtualenvs/test-O3eWbxRl-py3.7
Valid: True
System
Platform: darwin
OS: posix
Python: /path/to/main/python
```
If you only want to know the path to the virtual environment, you can pass the `--path` option
to `env info`:
```bash
poetry env info --path
```
## Listing the environments associated with the project
You can also list all the virtual environments associated with the current virtual environment
with the `env list` command:
```bash
poetry env list
```
will output something like the following:
```text
test-O3eWbxRl-py2.7
test-O3eWbxRl-py3.6
test-O3eWbxRl-py3.7 (Activated)
```
## Deleting the environments
Finally, you can delete existing virtual environments by using `env remove`:
```bash
poetry env remove /full/path/to/python
poetry env remove python3.7
poetry env remove 3.7
poetry env remove test-O3eWbxRl-py3.7
```
If your remove the currently activated virtual environment, it will be automatically deactivated.
docs/mkdocs.yml
...@@ -14,7 +14,8 @@ nav: ...@@ -14,7 +14,8 @@ nav:
- Commands: cli.md - Commands: cli.md
- Configuration: configuration.md - Configuration: configuration.md
- Repositories: repositories.md - Repositories: repositories.md
- Versions: versions.md - Managing environments: managing-environments.md
- Dependency specification: dependency-specification.md
- The pyproject.toml file: pyproject.md - The pyproject.toml file: pyproject.md
- Contributing: contributing.md - Contributing: contributing.md
- FAQ: faq.md - FAQ: faq.md
...@@ -25,3 +26,5 @@ markdown_extensions: ...@@ -25,3 +26,5 @@ markdown_extensions:
- pymdownx.superfences - pymdownx.superfences
- toc: - toc:
permalink: permalink:
- markdown_include.include:
base_path: docs
poetry.lock
...@@ -546,6 +546,17 @@ testing = ["coverage", "pyyaml"] ...@@ -546,6 +546,17 @@ testing = ["coverage", "pyyaml"]
[[package]] [[package]]
category = "dev" category = "dev"
description = "This is an extension to Python-Markdown which provides an \"include\" function, similar to that found in LaTeX (and also the C pre-processor and Fortran). I originally wrote it for my FORD Fortran auto-documentation generator."
name = "markdown-include"
optional = false
python-versions = "*"
version = "0.5.1"
[package.dependencies]
markdown = "*"
[[package]]
category = "dev"
description = "Safely add untrusted strings to HTML/XML markup." description = "Safely add untrusted strings to HTML/XML markup."
marker = "python_version >= \"2.7.9\" and python_version < \"2.8.0\" or python_version >= \"3.4\" and python_version < \"4.0\"" marker = "python_version >= \"2.7.9\" and python_version < \"2.8.0\" or python_version >= \"3.4\" and python_version < \"4.0\""
name = "markupsafe" name = "markupsafe"
...@@ -1296,7 +1307,7 @@ docs = ["sphinx", "jaraco.packaging (>=3.2)", "rst.linker (>=1.9)"] ...@@ -1296,7 +1307,7 @@ docs = ["sphinx", "jaraco.packaging (>=3.2)", "rst.linker (>=1.9)"]
testing = ["pathlib2", "contextlib2", "unittest2"] testing = ["pathlib2", "contextlib2", "unittest2"]
[metadata] [metadata]
content-hash = "8f22c8d88bf8371ff21b14d85e0bf0bd932540fa0e5990a72cdb3323a6bdc6c2" content-hash = "35feeab2d2e9415a82f714a41962c442ea8b302f0e8365c10ee188f31603684a"
python-versions = "~2.7 || ^3.4" python-versions = "~2.7 || ^3.4"
[metadata.files] [metadata.files]
...@@ -1543,6 +1554,9 @@ markdown = [ ...@@ -1543,6 +1554,9 @@ markdown = [
{file = "Markdown-3.1.1-py2.py3-none-any.whl", hash = "sha256:56a46ac655704b91e5b7e6326ce43d5ef72411376588afa1dd90e881b83c7e8c"}, {file = "Markdown-3.1.1-py2.py3-none-any.whl", hash = "sha256:56a46ac655704b91e5b7e6326ce43d5ef72411376588afa1dd90e881b83c7e8c"},
{file = "Markdown-3.1.1.tar.gz", hash = "sha256:2e50876bcdd74517e7b71f3e7a76102050edec255b3983403f1a63e7c8a41e7a"}, {file = "Markdown-3.1.1.tar.gz", hash = "sha256:2e50876bcdd74517e7b71f3e7a76102050edec255b3983403f1a63e7c8a41e7a"},
] ]
markdown-include = [
{file = "markdown-include-0.5.1.tar.gz", hash = "sha256:72a45461b589489a088753893bc95c5fa5909936186485f4ed55caa57d10250f"},
]
markupsafe = [ markupsafe = [
{file = "MarkupSafe-1.1.1-cp27-cp27m-macosx_10_6_intel.whl", hash = "sha256:09027a7803a62ca78792ad89403b1b7a73a01c8cb65909cd876f7fcebd79b161"}, {file = "MarkupSafe-1.1.1-cp27-cp27m-macosx_10_6_intel.whl", hash = "sha256:09027a7803a62ca78792ad89403b1b7a73a01c8cb65909cd876f7fcebd79b161"},
{file = "MarkupSafe-1.1.1-cp27-cp27m-manylinux1_i686.whl", hash = "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7"}, {file = "MarkupSafe-1.1.1-cp27-cp27m-manylinux1_i686.whl", hash = "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7"},
......
pyproject.toml
...@@ -70,6 +70,7 @@ pre-commit = "^1.10" ...@@ -70,6 +70,7 @@ pre-commit = "^1.10"
tox = "^3.0" tox = "^3.0"
pytest-sugar = "^0.9.2" pytest-sugar = "^0.9.2"
httpretty = "^0.9.6" httpretty = "^0.9.6"
markdown-include = "^0.5.1"
[tool.poetry.scripts] [tool.poetry.scripts]
poetry = "poetry.console:main" poetry = "poetry.console:main"
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment