Skip to content
Back to top
View this page

# Contributing to `xyzservices`

Contributions to `xyzservices` are very welcome. They are likely to be accepted more quickly if they follow these guidelines.

There are two main groups of contributions - adding new provider sources and contributions to the codebase and documentation.

## Providers

If you want to add a new provider, simply add its details to `provider_sources/xyzservices-providers.json`.

You can add a single `TileProvider` or a `Bunch` of `TileProviders`. Use the following schema to add a single provider:

    {
       "single_provider_name": {
          "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
          "max_zoom": 19,
          "attribution": "(C) OpenStreetMap contributors",
          "html_attribution": "&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors",
          "name": "OpenStreetMap.Mapnik"
       },
    }

If you want to add a bunch of related providers (different versions from a single source like `Stamen.Toner` and `Stamen.TonerLite`), you can group then within a `Bunch` using the following schema:

    {
      "provider_bunch_name": {
          "first_provider_name": {
                "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png",
                "max_zoom": 19,
                "attribution": "(C) OpenStreetMap contributors",
                "html_attribution": "&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors",
                "name": "OpenStreetMap.Mapnik"
          },
          "second_provider_name": {
                "url": "https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png?access-token={accessToken}",
                "max_zoom": 19,
                "attribution": "(C) OpenStreetMap contributors",
                "html_attribution": "&copy; <a href=\"https://www.openstreetmap.org/copyright\">OpenStreetMap</a> contributors",
                "name": "OpenStreetMap.Mapnik",
                "accessToken": "<insert your access token here>"
          }
       },
    }

It is mandatory to always specify at least `name`, `url`, and `attribution`. Don’t forget to add any other custom attribute required by the provider. When specifying a placeholder for the access token, please use the `"<insert your access token here>"` string to ensure that `requires_token()` method works properly. You can also specify the extent of the tile coverage using the `bounds` keyword and the format `[[lat_min, lon_min], [lat_max, lon_max]]`. See the example for the area surrounding Switzerland:

    {
      "bounds": [
          [
              45,
              5
          ],
          [
              48,
              11
          ]
      ],
    }

Once updated, you can (optionally) compress the provider sources by executing `make compress` from the repository root.

    cd xyzservices
    make compress

## Code and documentation

At this stage of `xyzservices` development, the priorities are to define a simple, usable, and stable API and to have clean, maintainable, readable code.

In general, `xyzservices` follows the conventions of the GeoPandas project where applicable.

In particular, when submitting a pull request:

- All existing tests should pass. Please make sure that the test suite passes, both locally and on GitHub Actions. Status on GHA will be visible on a pull request. GHA are automatically enabled on your own fork as well. To trigger a check, make a PR to your own fork.

- Ensure that documentation has built correctly. It will be automatically built for each PR.

- New functionality should include tests. Please write reasonable tests for your code and make sure that they pass on your pull request.

- Classes, methods, functions, etc. should have docstrings and type hints. The first line of a docstring should be a standalone summary. Parameters and return values should be documented explicitly.

- Follow PEP 8 when possible. We use Black and Flake8 to ensure a consistent code format throughout the project. For more details see the GeoPandas contributing guide.

- Imports should be grouped with standard library imports first, 3rd-party libraries next, and `xyzservices` imports third. Within each grouping, imports should be alphabetized. Always use absolute imports when possible, and explicit relative imports for local imports when necessary in tests.

- `xyzservices` supports Python 3.7+ only. When possible, do not introduce additional dependencies. If that is necessary, make sure they can be treated as optional.

## Updating sources from leaflet

`leaflet-providers-parsed.json` is an automatically generated file by GHA. You can create a fresh version using `make update-leaflet` from the repository root:

    cd xyzservices
    make update-leaflet

Note that you will need functional installation of `selenium` with Firefox webdriver, `git` and `html2text` packages.