Metadata-Version: 2.4
Name: dh_virtualenv
Version: 1.3.1
Summary: Debian packaging sequence for Python virtualenvs.
Project-URL: Source, https://salsa.debian.org/python-team/packages/dh-virtualenv
Project-URL: Bug Tracker, https://bugs.debian.org/dh-virtualenv
Author-email: Jyrki Pulliainen <jyrki@dywypi.org>, Nico Della Torre <nicoz91@ubuntu.com>
Maintainer-email: Debian Python Team <team+python@tracker.debian.org>
License-Expression: GPL-2.0-or-later
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# dh-virtualenv

[![Docs](https://img.shields.io/badge/docs-Salsa%20Pages-blue)](https://python-team.pages.debian.net/packages/dh-virtualenv)

**Contents**

  * [Overview](#overview)
  * [Presentations, Blogs & Other Resources](#presentations-blogs--other-resources)
  * [Using dh-virtualenv](#using-dh-virtualenv)
  * [How does it work?](#how-does-it-work)
  * [Running tests](#running-tests)
  * [Building the package in a Docker container](#building-the-package-in-a-docker-container)
  * [Building the documentation locally](#building-the-documentation-locally)
  * [Releasing a new version](#releasing-a-new-version)
  * [Code of conduct](#code-of-conduct)
  * [License](#license)


## Overview

dh-virtualenv is a tool that aims to combine Debian packaging with
self-contained virtualenv based Python deployments.

The idea behind dh-virtualenv is to be able to combine the power of
Debian packaging with the sandboxed nature of virtualenvs. In addition
to this, using virtualenv enables installing requirements via
[Python Package Index](https://pypi.org) instead of relying on
the operating system provided Python packages. The only limiting
factor is that you have to run the same Python interpreter as the
operating system.

For complete online documentation including installation instructions, see
[the online documentation](https://python-team.pages.debian.net/packages/dh-virtualenv/).


## Presentations, Blogs & Other Resources

Here are a few external resources that can help you
to get a more detailed first impression of dh-virtualenv,
or advocate its use in your company or project team.

* [How We Deploy Python Code](https://www.nylas.com/blog/packaging-deploying-python/)
  – Building, packaging & deploying Python using versioned artifacts in Debian packages at Nylas.
* [DevOps Tool Bazaar](https://speakerdeck.com/jhermann/devops-karlsruhe-meetup-2018-02-20)
  – Slide deck presented at the DevOps Karlsruhe Meetup in February 2018, regarding Python software deployment for Debian with a practical example.
* [The Architecture of Open Source Applications: Python Packaging](http://aosabook.org/en/packaging.html)
  – This provides a lot of background (and possibly things you didn't know) about the Python side of packaging.


## Using dh-virtualenv

Using dh-virtualenv is fairly straightforward. First, you need to
define the requirements of your package in `requirements.txt` file, in
[the format defined by pip](https://pip.pypa.io/en/latest/user_guide.html#requirements-files).

To build a package using dh-virtualenv, you need to add dh-virtualenv
in to your build dependencies and write following `debian/rules` file:

      %:
              dh $@ --with python-virtualenv

Note that you might need to provide
additional build dependencies too, if your requirements require them.

Also, you are able to define the root path for your source directory using
`--sourcedirectory` or `-D` argument:

      %:
              dh $@ --with python-virtualenv --sourcedirectory=root/srv/application

NOTE: Be aware that the configuration in debian/rules expects tabs instead of spaces!

Once the package is built, you have a virtualenv contained in a Debian
package and upon installation it gets placed, by default, under
`/opt/venvs/<packagename>`.

For more information and usage documentation, check the accompanying
documentation in the `doc` folder, also available at
[Salsa Pages](https://python-team.pages.debian.net/packages/dh-virtualenv/).


## How does it work?

To do the packaging, *dh-virtualenv* extends debhelper's sequence by
inserting a new `dh_virtualenv` command, which effectively replaces
the following commands in the original sequence:

* `dh_auto_configure`
* `dh_auto_build`
* `dh_auto_test`
* `dh_auto_install`
* `dh_auto_clean`

In the new sequence, `dh_virtualenv` is inserted right before `dh_installinit`.


## Running tests

    $ python3 -m pytest test/


## Building the package in a Docker container

To build ``dh-virtualenv`` itself in a Docker container, call ``docker build --tag dh-venv-builder .``.
This will build the DEB package for Debian stable by default.
Add e.g. ``--build-arg distro=debian:testing`` to build for another release.

The resulting files must be copied out of the build container, using these commands:

```sh
mkdir -p dist && docker run --rm dh-venv-builder tar -C /dpkg -c . | tar -C dist -xv
```


## Building the documentation locally

Install Sphinx and the Read the Docs theme, then build the documentation
into ``doc/_build/html`` from your clone of the repository:

```sh
sudo apt install python3-sphinx python3-sphinx-rtd-theme
PYTHONPATH=. python3 -m sphinx -b html -N doc doc/_build/html
```


## Releasing a new version

Follow these steps when creating a new release:

1. Check that the version in `dh_virtualenv/__init__.py` matches `debian/changelog`.
1. Set the release and its date in `debian/changelog` (`dch -r`).
1. Tag the release with `gbp tag` and push only that tag.


## Code of conduct

This project follows the [Debian Code of Conduct][code-of-conduct].
By participating, you are expected to honor this code.


## License

Copyright (c) 2013-2017 Spotify AB
Copyright (c) 2026 Nico Della Torre

dh-virtualenv is licensed under GPL v2 or later. Full license is
available in the `LICENSE` file.

[code-of-conduct]: https://www.debian.org/code_of_conduct
