Metadata-Version: 2.1
Name: flitenv
Version: 0.3.4
Summary: Manage venvs for a flit project
Home-page: https://github.com/orsinium-labs/flitenv
License: MIT
Keywords: flit,venv
Author: Gram
Author-email: gram@orsinium.dev
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: flit
Requires-Dist: pip-tools
Requires-Dist: toml
Requires-Dist: flake8 ; extra == "lint"
Requires-Dist: isort ; extra == "lint"
Requires-Dist: mypy ; extra == "lint"
Requires-Dist: types-toml ; extra == "lint"
Requires-Dist: pytest ; extra == "test"
Provides-Extra: lint
Provides-Extra: test

# 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 lint install`: 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 lint run flake8`: run a command. If the venv doesn't exist, it will be created, and the dependencies will be installed.
+ `flitenv lint lock`: 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 lint install`: 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.

