Poetry's dependencies divide into 2 groups and both of them can be optional or required:

Development
Production

Production dependencies are installed when your library is installed by a user (usually package is installed from PyPI)

Development dependencies are installed when your library is installed by a contributor with purpose of adding new feature to your library (always package is installed from source, i.e from GitHub)

All dependencies' information is stored in pyproject.toml file. The dependencies' source code is in the .venv folder

How does optional dependencies work?

All optional dependencies divide into groups by a developer

For example, some dependencies are required to build documentation. You can view dev-docs group of dependencies in pyproject.toml. If you need to install only them as optional you can execute this

Terminal

pip install library[dev-docs]

Separate by a comma optional dependencies in brackets ([])

Anyway, you do not need to install any development dependencies when you install a package from PyPI as a user. It's for an example

Any group from dev dependencies could be also installed with make out of library source

Terminal

make install-dev-docs

Why the template does not use dev-dependencies section?

Because now Poetry does not support dev-dependencies with extras. The template have many development dependencies and full installation of them takes quite long time so division is required

Check out this:

Install the project from source in development mode

make install-dev-all will install all development dependencies. If you need only a part of them, check out the Makefile and find a command for your purpose

Install the project from source in production mode

make install-production will install only required dependencies and the library should be ready for usage

Feature

You can add the library code as dependency as Git Submodule

Add a non-optional dependency

For example, you want to add a requests as dependency for project, so it should be installed when your library is installed

Terminal

poetry add requests

Now when someone installs your library, requests will be installed too

Add an optional dependency

For example, you want to optimize JSON parsing in your project with orjson library (as it is written on Rust and requires rustc). You can do not force user install orjson and keep orjson as optional

Terminal

poetry add orjson --optional

As it's an optional, you should add it to a special group of optional dependencies.

Your pyproject.toml looks like this

pyproject.toml

...
[tool.poetry.dependencies]
orjson = {optional = true, version="^3.6.5"}
...

And now add the dependency to a new group. Let's call it fast-json

pyproject.toml

[tool.poetry.extras]
# Ordinary extra dependencies
all = []

# Fast and optimized JSON parsers
fast-json = ["orjson"]
...

It's a good practice to unite all your optional dependencies into a all group so add it there too

pyproject.toml

[tool.poetry.extras]
# Ordinary extra dependencies
all = ["orjson"]

# Fast and optimized JSON parsers
fast-json = ["orjson"]
...

Add a non-optional dev dependency

Terminal

poetry add pytest --dev

pytest will be installed every time your library is installed in development mode

Add an optional dev dependency

Terminal

poetry add pytest-asyncio --optional

It looks like optional production dependency, but now we should change extra section in another way.

All optional development dependencies groups marked with prefix dev-. So our pytest-asyncio should be addd in such groups.

Check out pyproject.toml. There is an existed group of optional dependencies used for testing (as pytest-asyncio too)

pyproject.toml

[tool.poetry.extra]
...
dev-test = ["pytest", "pytest-cov", "coveralls", "coverage"]

Now put it here

pyproject.toml

[tool.poetry.extra]
...
dev-test = ["pytest-asyncio", "pytest", "pytest-cov", "coveralls", "coverage"]

And there is also a dev-all group that need to be modified

pyproject.toml

[tool.poetry.extra]
...
dev-test = ["pytest-asyncio", "pytest", "pytest-cov", "coveralls", "coverage"]
...
dev-all = [
    "black", "isort", "pre-commit",
    "pytest", "pytest-cov", "pytest-asyncio"
    "coveralls", "coverage",
    "mypy",
    "bumpversion",
    "autoflake",
    "mkdocs", "mkdocs-material", "mike"
]