flitenv 0.4.0
Manage venvs for a flit project
License: MIT
Requires Python: >=3.6
Keywords: flit,venv

# flitenv

Manage [venvs](https://docs.python.org/3/library/venv.html) and dependencies for [flit](https://flit.pypa.io/en/latest/) projects.

Features:

+ Supports the most modern metadata format described in [PEP 621](https://peps.python.org/pep-0621/).
+ Locks dependencies using [pip-tools](https://github.com/jazzband/pip-tools).
+ Multiple venvs per project to ensure a better isolation of environments.
+ No vendor lock, under-the-hood uses popular and well-maintained technologies and tool-agnostic formats.
+ Cross-platform.
+ Battle-tested.

## Installation

```bash
python3 -m pip install flitenv
```

## Usage

Basics:

1. The project stores metadata in a [flit](https://flit.pypa.io/en/latest/)-compatible format, [as described in the flit documentation](https://flit.pypa.io/en/latest/pyproject_toml.html). The recommended ways is to us the new `[project]` section introduced in [PEP 621](https://peps.python.org/pep-0621/).
1. Direct required production dependencies of the project are described in `dependencies` list. This environment is called `main`.
1. Development environments are described in the `[project.optional-dependencies]` section. Good examples of such environments are `test`, `lint`, and `doc`.
1. For each environment, flitenv will create a separate [venv](https://docs.python.org/3/library/venv.html) in `.venvs` to ensure a good isolation.
1. "Lock file" is a file with exact versions of all dependencies of the project in the given environment, including the transitive ones.
1. Flitenv uses [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files) files generated by [pip-tools](https://github.com/jazzband/pip-tools) as lock files.
1. It is recommend to generate a lock file for (and only for) the `main` environment.
1. flitenv follows the flit philosophy. It provides only the most helpful and flexible commands, and you can do anything you ever need by combining them with each other and with other tools.

Below are usage examples. Each example uses `lint` as the target environment and `flake8` as a command we want to run in this environment.

+ `flitenv install lint`: install dependencies. If the venv doesn't exist, it will be created. Can also be used to upgrade dependencies when the lock file has been changed.
+ `flitenv run lint flake8`: run a command. If the venv doesn't exist, it will be created, and the dependencies will be installed.
+ `flitenv lock lint`: generate lock file (`requirements-lint.txt`) for the env.
+ `flitenv main lock`: generate lock file (`requirements.txt`) for the `main` env. If there is no env-specific lock file, this one will be used instead.
+ `flitenv main lock -c ../other-project/requirements.txt`: generate lock file using lock file from another project as a reference. It allows to ensure compatibility of lock files accross multiple projects.
+ `rm requirements.txt && flitenv main lock`: upgrade all dependencies in the lock file.
+ `rm -rf .venvs/lint && flitenv install lint`: re-create the venv. It is usefult to ensure that all old dependencies.
+ `flit build`: build a distribution for the project.
+ `flit install --symlink --python $(which python3.9) --deps=none`: symlink the project into the given Python interpreter without installing dependencies. It is helpful if you want to have nice go-to-definition in vscode across multiple projects.