xlsform2qgis - library to convert XLSForms to QGIS project files

A library used to generate a valid QGIS project out of a given XLSForm file.

Compatable with PyQt5, qgis 3.36+ and python 3.10+

Installation

Prerequisite: This library requires QGIS to be installed on your system, as it depends on qgis and PyQt libraries that are not available on PyPI. Install QGIS from qgis.org before proceeding.

Install the package from PyPI:

pip install xlsform2qgis

Usage

You can use the library by simply importing:

from xlsform2qgis.converter import XLSFormConverter

converter = XLSFormConverter("input_xlsform.xls")
converter.convert("output_qgis_directory")

Or by running from the commandline:

uv run xlsform2qgis ./samples/service_rating.xlsx ./output/

Development

1. Clone the repository and enter it's directory:

git clone git@github.com:opengisch/xlsform2qgis.git
cd xlsform2qgis

2. This repository uses the pre-commit project. Install it on this project.

pre-commit install

3. This repository uses the uv project. Create a new environment.

uv venv

4. Manually add the externally managed PyQt5 and qgis libraries to your environment:

ln -s /usr/lib/python3/dist-packages/qgis .venv/lib/python3.12/site-packages/
ln -s /usr/lib/python3/dist-packages/PyQt5 .venv/lib/python3.12/site-packages/

5. OPTIONAL Add the xlsform2qgis library system wide in all Python scripts as editable module. This will allow developing xlsform2qgis in parallel with other projects, such as the XLSFormConverter QGIS Plugin.

sudo uv pip install --system --break-system-packages --editable .

Debugging

If you are using VS Code and want to debug test and debug the project, run:

uv run python3 -m debugpy --listen 5678 --wait-for-client ./src/xlsform2qgis/converter.py ./samples/service_rating.xlsx ./output/

Testing

To run all tests:

uv run pytest

To run a specific test:

uv run pytest -k test_converter