Wine Python Environment

The wenv package

zugbruecke runs on top of a Windows build of CPython on top of Wine. A dedicated Wine Python Environment, a special kind of Python virtual environment, is created underneath the currently activated Unix Python Environment. This entire mechanism is managed by a dedicated Python package named wenv.

Note

The functionality of wenv has its origin in zugbruecke and was eventually consolidated into its own separate Python package. wenv offers a sophisticated Command Line Interface (CLI) as well as an API for managing and working with Windows Python on top of Wine. For more details, see wenv documentation.

The zugbruecke.Env class

The zugbruecke package offers its own version of the wenv.Env class, essentially inheriting from it and extending it.

class zugbruecke.Env(**kwargs)

Bases: Env

Represents one Wine Python environment. Derived from wenv.Env. Mutable.

Parameters

kwargs (Any) – An arbitrary number of keyword arguments matching valid wenv configuration options.

cache()

Equivalent to wenv cache. It fetches installation files and caches them for offline usage, including the Python interpreter, pip, setuptools and wheel.

cache_package(name)

Caches a specific package by nameself.

Parameters

name (str) – Name of PyPI package

cli()

Command line interface entry point. Equivalent to wenv [...]. Looks for sub-commands and parameters in sys.argv.

cpython_31542_pth_workaround()

Deletes pth-file or reconstructs it from backup depending on no_pth_file configuration parameter. Relevant for prepending "" to sys.path in CPython >= 3.11 thanks to CPython PR #31542. This function works around “Modules/getpath.py sets safe_path to 1 if a “._pth” file is present”.

ensure()

Equivalent to wenv init. Intended to be used by 3rd-party packages which want to “ensure” that wenv has been initialized (i.e. Python and pip are present and working). ensure() calls the following methods:

  • wenv.Env.setup_wineprefix()

  • wenv.Env.setup_pythonprefix()

  • wenv.Env.wine_47766_workaround()

  • wenv.Env.setup_pip()

install_package(name, update=False)

Thin wrapper for wenv pip install {-U} {name}. Installs and/or updates a package.

Parameters

  • name (str) – Name of PyPI package

  • update (bool) – Update flag

list_packages()

Thin wrapper for wenv pip list --format json.

Return type

List[Dict[str, str]]

Returns

A list of dictionaries of format {"name": "Name of PyPI package ", "version": "package version"}.

setup_coverage_activate()

Equivalent to wenv init_coverage. It enables coverage analysis inside wenv.

setup_pip()

Part of the initialization process, but can be triggered on its own if required. It installs pip, assuming that both the wineprefix and pythonprefix are already present.

setup_pythonprefix(overwrite=False)

Part of the initialization process, but can be triggered on its own if required. It installs the CPython interpreter into the Python prefix.

Parameters

overwrite (bool) – If set to True, a pre-existing Python prefix is removed before a new one is created.

setup_wineprefix(overwrite=False)

Part of the initialization process, but can be triggered on its own if required. It creates a Wine prefix according to wenv’s configuration.

Parameters

overwrite (bool) – If set to True, a pre-existing Wine prefix is removed before a new one is created.

setup_zugbruecke()

Creates symlinks from site-packages folder in the Unix Python environment into the site-packages folder in the Windows Python environment for the following packages:

  • zugbruecke

  • wenv

Should any of the above packages be updated on the Unix side, the update automatically becomes available on the Wine side.

shebang()

shebang entry point for Wine Python interpreter. Equivalent to _wenv_python [...]. Does not look at sys.argv. It only passes sys.argv[1] on to the Wine Python interpreter.

This interface is working around a lack of Unix specification, see:

uninstall()

Equivalent to wenv clean. It removes the current Wine Python environment, i.e. Python interpreter, pip, setuptools, wheel and all installed packages.

uninstall_package(name)

Thin wrapper for wenv pip uninstall -y {name}. Removes a package.

Parameters

name (str) – Name of PyPI package

wine_47766_workaround()

Due to Wine bug #47766 (in PathAllocCanonicalize), Wine crashes if any folder in the path to pythonprefix is hidden Unix-style (i.e. prefixed with a dot / .). This workaround creates a symlink directly pointing to pythonprefix into /tmp, which is (more or less) guaranteed to be visible. It is then used instead of the actual pythonprefix.

Run setup_wineprefix and setup_pythonprefix before calling wine_47766_workaround. Any subsequent action such as installing or using pip must happen after calling wine_47766_workaround.

wine_47766_workaround_uninstall()

Reverts the Wine bug #47766 workaround, i.e. it removes the symlink.