"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "docs/basic-usage.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.

basic-usage.md  (poetry-1.1.15)	:	basic-usage.md  (poetry-1.2.0)
skipping to change at line 15		skipping to change at line 15
layout: single		layout: single
menu:		menu:
docs:		docs:
weight: 10		weight: 10
---		---
# Basic usage		# Basic usage
For the basic usage introduction we will be installing `pendulum`, a datetime li brary.		For the basic usage introduction we will be installing `pendulum`, a datetime li brary.
If you have not yet installed Poetry, refer to the [Introduction]({{< relref "." >}} "Introduction") chapter.		If you have not yet installed Poetry, refer to the [Introduction]({{< relref "do cs" >}} "Introduction") chapter.
## Project setup		## Project setup
First, let's create our new project, let's call it `poetry-demo`:		First, let's create our new project, let's call it `poetry-demo`:
```bash		```bash
poetry new poetry-demo		poetry new poetry-demo
```		```
This will create the `poetry-demo` directory with the following content:		This will create the `poetry-demo` directory with the following content:
```text		```text
poetry-demo		poetry-demo
├── pyproject.toml		├── pyproject.toml
├── README.rst		├── README.md
├── poetry_demo		├── poetry_demo
│ └── __init__.py		│ └── __init__.py
└── tests		└── tests
├── __init__.py		└── __init__.py
└── test_poetry_demo.py
```		```
The `pyproject.toml` file is what is the most important here. This will orchestr ate		The `pyproject.toml` file is what is the most important here. This will orchestr ate
your project and its dependencies. For now, it looks like this:		your project and its dependencies. For now, it looks like this:
```toml		```toml
[tool.poetry]		[tool.poetry]
name = "poetry-demo"		name = "poetry-demo"
version = "0.1.0"		version = "0.1.0"
description = ""		description = ""
authors = ["Sébastien Eustace <sebastien@eustace.io>"]		authors = ["Sébastien Eustace <sebastien@eustace.io>"]
		readme = "README.md"
		packages = [{include = "poetry_demo"}]
[tool.poetry.dependencies]		[tool.poetry.dependencies]
python = "*"		python = "^3.7"
[tool.poetry.dev-dependencies]		[build-system]
pytest = "^3.4"		requires = ["poetry-core"]
		build-backend = "poetry.core.masonry.api"
```		```
		Poetry assumes your package contains a package with the same name as `tool.poetr
		y.name`.
		If this is not the case, populate `tool.poetry.packages` to specify your package
		or packages.
		See [Packages]({{< relref "pyproject#packages" >}}) for more information.
### Initialising a pre-existing project		### Initialising a pre-existing project
Instead of creating a new project, Poetry can be used to 'initialise' a pre-popu lated		Instead of creating a new project, Poetry can be used to 'initialise' a pre-popu lated
directory. To interactively create a `pyproject.toml` file in directory `pre-exi sting-project`:		directory. To interactively create a `pyproject.toml` file in directory `pre-exi sting-project`:
```bash		```bash
cd pre-existing-project		cd pre-existing-project
poetry init		poetry init
```		```
### Specifying dependencies		### Specifying dependencies
If you want to add dependencies to your project, you can specify them in the `to ol.poetry.dependencies` section.		If you want to add dependencies to your project, you can specify them in the `to ol.poetry.dependencies` section.
```toml		```toml
[tool.poetry.dependencies]		[tool.poetry.dependencies]
pendulum = "^1.4"		pendulum = "^2.1"
```		```
As you can see, it takes a mapping of **package names** and **version constraint s**.		As you can see, it takes a mapping of **package names** and **version constraint s**.
Poetry uses this information to search for the right set of files in package "re positories" that you register		Poetry uses this information to search for the right set of files in package "re positories" that you register
in the `tool.poetry.repositories` section, or on [PyPI](https://pypi.org) by def ault.		in the `tool.poetry.source` section, or on [PyPI](https://pypi.org) by default.
Also, instead of modifying the `pyproject.toml` file by hand, you can use the `a dd` command.		Also, instead of modifying the `pyproject.toml` file by hand, you can use the `a dd` command.
```bash		```bash
$ poetry add pendulum		$ poetry add pendulum
```		```
It will automatically find a suitable version constraint **and install** the pac kage and subdependencies.		It will automatically find a suitable version constraint **and install** the pac kage and sub-dependencies.
## Using your virtual environment		## Using your virtual environment
By default, poetry creates a virtual environment in `{cache-dir}/virtualenvs` (` {cache-dir}\virtualenvs` on Windows).		By default, poetry creates a virtual environment in `{cache-dir}/virtualenvs` (` {cache-dir}\virtualenvs` on Windows).
You can change the [`cache-dir`]({{< relref "configuration#cache-dir" >}} "cache -dir configuration documentation") value by editing the poetry config.		You can change the [`cache-dir`]({{< relref "configuration#cache-dir" >}} "cache -dir configuration documentation") value by editing the poetry config.
Additionally, you can use the [`virtualenvs.in-project`]({{< relref "configurati on#virtualenvsin-project" >}} "virtualenv.in-project configuration documentation ") configuration variable		Additionally, you can use the [`virtualenvs.in-project`]({{< relref "configurati on#virtualenvsin-project" >}} "#virtualenvs.in-project configuration documentati on") configuration variable
to create virtual environment within your project directory.		to create virtual environment within your project directory.
There are several ways to run commands within this virtual environment.		There are several ways to run commands within this virtual environment.
### Using `poetry run`		### Using `poetry run`
To run your script simply use `poetry run python your_script.py`.		To run your script simply use `poetry run python your_script.py`.
Likewise if you have command line tools such as `pytest` or `black` you can run them using `poetry run pytest`.		Likewise if you have command line tools such as `pytest` or `black` you can run them using `poetry run pytest`.
### Activating the virtual environment		### Activating the virtual environment
skipping to change at line 117		skipping to change at line 124
{{% note %}}		{{% note %}}
**Why a new shell?**		**Why a new shell?**
Child processes inherit their environment from their parents, but do not share		Child processes inherit their environment from their parents, but do not share
them. As such, any modifications made by a child process, is not persisted after		them. As such, any modifications made by a child process, is not persisted after
the child process exits. A Python application (Poetry), being a child process,		the child process exits. A Python application (Poetry), being a child process,
cannot modify the environment of the shell that it has been called from such		cannot modify the environment of the shell that it has been called from such
that an activated virtual environment remains active after the Poetry command		that an activated virtual environment remains active after the Poetry command
has completed execution.		has completed execution.
Therefore, Poetry has to create a sub-shell with the virtual envrionment activat ed		Therefore, Poetry has to create a sub-shell with the virtual environment activat ed
in order for the subsequent commands to run from within the virtual environment.		in order for the subsequent commands to run from within the virtual environment.
{{% /note %}}		{{% /note %}}
Alternatively, to avoid creating a new shell, you can manually activate the		Alternatively, to avoid creating a new shell, you can manually activate the
virtual environment by running `source {path_to_venv}/bin/activate` (`source {pa th_to_venv}\Scripts\activate.bat` on Windows).		virtual environment by running `source {path_to_venv}/bin/activate` (`{path_to_v env}\Scripts\activate.ps1` on Windows PowerShell).
To get the path to your virtual environment run `poetry env info --path`.		To get the path to your virtual environment run `poetry env info --path`.
You can also combine these into a nice one-liner, `source $(poetry env info --pa th)/bin/activate`		You can also combine these into a nice one-liner, `source $(poetry env info --pa th)/bin/activate`
To deactivate this virtual environment simply use `deactivate`.		To deactivate this virtual environment simply use `deactivate`.
| | POSIX Shell | Windows		| | POSIX Shell | Windows
| Exit/Deactivate |		(PowerShell) | Exit/Deactivate |
|-------------------|------------------------------------------------|----------		| ----------------- | ----------------------------------------------- | --------
-----------------------------------|-----------------|		----------------------------- | --------------- |
| New Shell | `poetry shell` | `poetry s		| New Shell | `poetry shell` | `poetry
hell` | `exit` |		shell` | `exit` |
| Manual Activation | `source {path_to_venv}/bin/activate` | `source {		| Manual Activation | `source {path_to_venv}/bin/activate` | `{path_t
path_to_venv}\Scripts\activate.bat`| `deactivate` |		o_venv}\Scripts\activate.ps1` | `deactivate` |
| One-liner | ```source`poetry env info --path`/bin/activate```|		| One-liner | `source $(poetry env info --path)/bin/activate` |
| `deactivate` |		| `deactivate` |
### Version constraints		### Version constraints
In our example, we are requesting the `pendulum` package with the version constr		In our example, we are requesting the `pendulum` package with the version constr
aint `^1.4`.		aint `^2.1`.
This means any version greater or equal to 1.4.0 and less than 2.0.0 (`>=1.4.0 <		This means any version greater or equal to 2.1.0 and less than 3.0.0 (`>=2.1.0 <
2.0.0`).		3.0.0`).
Please read [Dependency specification]({{< relref "dependency-specification" >}} "Dependency specification documentation") for more in-depth information on vers ions,		Please read [Dependency specification]({{< relref "dependency-specification" >}} "Dependency specification documentation") for more in-depth information on vers ions,
how versions relate to each other, and on the different ways you can specify dep endencies.		how versions relate to each other, and on the different ways you can specify dep endencies.
{{% note %}}		{{% note %}}
**How does Poetry download the right files?**		**How does Poetry download the right files?**
When you specify a dependency in `pyproject.toml`, Poetry first takes the name o f the package		When you specify a dependency in `pyproject.toml`, Poetry first takes the name o f the package
that you have requested and searches for it in any repository you have registere d using the `repositories` key.		that you have requested and searches for it in any repository you have registere d using the `repositories` key.
If you have not registered any extra repositories, or it does not find a package with that name in the		If you have not registered any extra repositories, or it does not find a package with that name in the
repositories you have specified, it falls back on PyPI.		repositories you have specified, it falls back on PyPI.
When Poetry finds the right package, it then attempts to find the best match		When Poetry finds the right package, it then attempts to find the best match
for the version constraint you have specified.		for the version constraint you have specified.
{{% /note %}}		{{% /note %}}
## Installing dependencies		## Installing dependencies
To install the defined dependencies for your project, just run the `install` com mand.		To install the defined dependencies for your project, just run the [`install`]({ {< relref "cli#install" >}}) command.
```bash		```bash
poetry install		poetry install
```		```
When you run this command, one of two things may happen:		When you run this command, one of two things may happen:
### Installing without `poetry.lock`		### Installing without `poetry.lock`
If you have never run the command before and there is also no `poetry.lock` file present,		If you have never run the command before and there is also no `poetry.lock` file present,
Poetry simply resolves all dependencies listed in your `pyproject.toml` file and downloads the latest version of their files.		Poetry simply resolves all dependencies listed in your `pyproject.toml` file and downloads the latest version of their files.
When Poetry has finished installing, it writes all of the packages and the exact versions of them that it downloaded to the `poetry.lock` file,		When Poetry has finished installing, it writes all the packages and their exact versions that it downloaded to the `poetry.lock` file,
locking the project to those specific versions.		locking the project to those specific versions.
You should commit the `poetry.lock` file to your project repo so that all people working on the project are locked to the same versions of dependencies (more be low).		You should commit the `poetry.lock` file to your project repo so that all people working on the project are locked to the same versions of dependencies (more be low).
### Installing with `poetry.lock`		### Installing with `poetry.lock`
This brings us to the second scenario. If there is already a `poetry.lock` file as well as a `pyproject.toml` file		This brings us to the second scenario. If there is already a `poetry.lock` file as well as a `pyproject.toml` file
when you run `poetry install`, it means either you ran the `install` command bef ore,		when you run `poetry install`, it means either you ran the `install` command bef ore,
or someone else on the project ran the `install` command and committed the `poet ry.lock` file to the project (which is good).		or someone else on the project ran the `install` command and committed the `poet ry.lock` file to the project (which is good).
Either way, running `install` when a `poetry.lock` file is present resolves and installs all dependencies that you listed in `pyproject.toml`,		Either way, running `install` when a `poetry.lock` file is present resolves and installs all dependencies that you listed in `pyproject.toml`,
but Poetry uses the exact versions listed in `poetry.lock` to ensure that the pa ckage versions are consistent for everyone working on your project.		but Poetry uses the exact versions listed in `poetry.lock` to ensure that the pa ckage versions are consistent for everyone working on your project.
As a result you will have all dependencies requested by your `pyproject.toml` fi le,		As a result you will have all dependencies requested by your `pyproject.toml` fi le,
but they may not all be at the very latest available versions		but they may not all be at the very latest available versions
(some of the dependencies listed in the `poetry.lock` file may have released new er versions since the file was created).		(some dependencies listed in the `poetry.lock` file may have released newer vers ions since the file was created).
This is by design, it ensures that your project does not break because of unexpe cted changes in dependencies.		This is by design, it ensures that your project does not break because of unexpe cted changes in dependencies.
### Commit your `poetry.lock` file to version control		### Commit your `poetry.lock` file to version control
Committing this file to VC is important because it will cause anyone who sets up the project		Committing this file to VC is important because it will cause anyone who sets up the project
to use the exact same versions of the dependencies that you are using.		to use the exact same versions of the dependencies that you are using.
Your CI server, production machines, other developers in your team,		Your CI server, production machines, other developers in your team,
everything and everyone runs on the same dependencies,		everything and everyone runs on the same dependencies,
which mitigates the potential for bugs affecting only some parts of the deployme nts.		which mitigates the potential for bugs affecting only some parts of the deployme nts.
Even if you develop alone, in six months when reinstalling the project you can f eel confident		Even if you develop alone, in six months when reinstalling the project you can f eel confident
the dependencies installed are still working even if your dependencies released many new versions since then.		the dependencies installed are still working even if your dependencies released many new versions since then.
(See note below about using the update command.)		(See note below about using the update command.)
{{% note %}}		{{% note %}}
For libraries it is not necessary to commit the lock file.		For libraries it is not necessary to commit the lock file.
{{% /note %}}		{{% /note %}}
### Installing dependencies only		### Installing dependencies only
The current project is installed in [editable](https://pip.pypa.io/en/stable/ref erence/pip_install/#editable-installs) mode by default.		The current project is installed in [editable](https://pip.pypa.io/en/stable/top ics/local-project-installs/) mode by default.
If you want to install the dependencies only, run the `install` command with the `--no-root` flag:		If you want to install the dependencies only, run the `install` command with the `--no-root` flag:
```bash		```bash
poetry install --no-root		poetry install --no-root
```		```
## Updating dependencies to their latest versions		## Updating dependencies to their latest versions
As mentioned above, the `poetry.lock` file prevents you from automatically getti ng the latest versions		As mentioned above, the `poetry.lock` file prevents you from automatically getti ng the latest versions
End of changes. 19 change blocks.
31 lines changed or deleted		40 lines changed or added

---