superset-wfs-dialect 0.0.14

SQLAlchemy dialect for OGC WFS

SQLAlchemy dialect for OGC WFS

SQLAlchemy dialect for OGC WFS as a Superset plugin.

Register the dialect

Create a requirements-local.txt file according to the superset documentation and insert following line:

superset_wfs_dialect

The dialect must then be registered in your superset config file, e.g. superset_config_docker.py when using the docker setup:

from sqlalchemy.dialects import registry
registry.register("wfs", "superset_wfs_dialect.dialect", "WfsDialect")

Start/restart superset and continue as described in the Start the application section.

Add a WFS database connection

• select Data > Connect database in the submenu
• select "OGC WFS" at the list of "Supported Databases"
• insert the WFS URL into the host field (e.g. https://example.com/geoserver/wfs)
• if the service is secured via BasicAuth, add username and password via the provided fields
• if the service is secured via OIDC/OAUTH2, add the required parameters into the OAuth2 client information section
  • required fields: Client ID, Client Secret, Token Request URI
  • optional fields: Scopes
  • fields to ignore: Authorization Request URI (added by superset but not needed for the client credentials flow)
• the WFS must support GeoJSON output (e.g outputFormat=application/json), and needs to support EPSG:4326 as coordinate reference system
• create a dataset
• create a chart/dashboard

Development

Prerequisites for development

• Docker Engine >= version 28
• python >= version 3.10.12
• Checkout this project

Installation

For debugging and code completion run via terminal within the project root:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

or create a virtual environment via VS Code:

https://code.visualstudio.com/docs/python/python-tutorial#_create-a-virtual-environment.

Start superset with the registered plugin:

docker compose up -d --build

Integrate with a local Superset checkout (editable mode)

If you are developing this dialect together with a local Superset checkout, use an editable install inside the Superset container so code changes in this repository are picked up immediately.

• Superset is checked out in a sibling directory, e.g.
  • ../superset
  • ../superset_wfs_dialect
• Superset is started via Docker Compose in development mode

In the Superset checkout:

1. Mount this repository into the Superset containers (e.g. /app/superset_wfs_dialect).

2. Add this line to docker/requirements-local.txt:

   -e /app/superset_wfs_dialect
   

3. Register the dialect in docker/pythonpath_dev/superset_config_docker.py:

   from sqlalchemy.dialects import registry
   registry.register("wfs", "superset_wfs_dialect.dialect", "WfsDialect")
   

4. Set the DEBUGGER env variable for the superset service in superset/docker-compose.yml to "1" to enable debugging in the container.

5. Restart the relevant services, for example:

   docker compose restart superset superset-worker superset-worker-beat
   

After restart, connect a database in Superset using a wfs://... SQLAlchemy URI as described above.

Debugging during development

Debugging can be activated via the VS Code during development using F5. Please note that the Python interpreter is selected from the previously created venv. Breakpoints set in VS Code are then taken into account.

Start the application

When in development mode, open http://localhost:8088/ . Otherwise, please open the corresponding URL to the installed superset instance.

Publishing a Development Version to PyPI

Requirements

• You must be on the main branch
• Your working directory must be clean (no uncommitted changes)
• You have push access to the repository
• A valid PYPI_TOKEN is configured in GitHub Secrets (used by the GitHub Actions workflow)

Releasing a new version

1. Run the release script with the desired version number (e.g. 0.0.1):

   ./release.sh 0.0.1
   

   This will:

   • Update the version field in setup.py
   • Commit the change to main
   • Create a Git tag e.g. 0.0.1
   • Push the tag to GitHub

2. The GitHub Actions workflow will be triggered by the tag:

   • It will build the package
   • Upload it to PyPI

Notes

• Versions must follow the format X.Y.Z (e.g. 0.1.0)