geoserver-py 0.2.1

Unofficial GeoServer python client. Manage workspaces, permissions, upload vectors, rasters and more. Check out the documentation for more information!
We are looking for contributors and feedbacks!

❓ About

This python package provides a simple interface to communicate with GeoServer. It implements most of the GeoServer REST API endpoints, allowing users to interact with GeoServer programmatically.

Why?

The purpose of this package is to implement the REST API endpoints with full type hints and documentation. This package does not aim to provide a high-level abstraction over the GeoServer REST API, thus it is expected that you have some knowledge of the GeoServer REST API.

Features

This package supports both JSON and XML requests and responses. It provides type hints for all the methods and classes, making it easier to work with the package.

[!NOTE] This package only relies on requests as a dependency, which make it extremely lightweight and easy to install: no need to install GDAL!

Get requests

# As JSON
workspaces = geoserver.get_workspaces()  # default is "json"

# As XML
workspaces = geoserver.get_workspaces(format="xml")

Post requests

# As JSON
geoserver.create_workspace(body={"workspace": {"name": "new_workspace"}})

# As XML
geoserver.create_workspace(body="<workspace><name>new_workspace</name></workspace>")

Documentation

We provide several examples and a documentation to help you get started,

🚀 Quick Start

This section will guide you on how to setup and use the package.

Installation

pip install geoserver-py

Usage

from geoserver import GeoServer

# Connect to a GeoServer instance
geoserver = GeoServer(
    service_url="http://localhost:8080/geoserver",
    username="admin",
    password="geoserver"
)

# Get all workspaces
workspaces = geoserver.get_workspaces()

# Create a workspace
geoserver.create_workspace_from_name(name="my_workspace")
# or geoserver.create_workspace(body={"workspace": {"name": "my_workspace"}})

# Get all datastores
datastores = geoserver.get_data_stores(workspace="my_workspace")

# Upload a Shapefile
geoserver.upload_data_store(file="path/to/file.shp", workspace="my_workspace")

# Upload a GeoTIFF
geoserver.upload_coverage_store(file="path/to/file.tif", format="geotiff", workspace="my_workspace")

# Upload a style
geoserver.upload_style(file="path/to/file.sld", workspace="my_workspace")

# etc.

📚 Examples

We provide several examples in the notebooks folder. These examples are based on the GeoServer REST API documentation.

🤗 Contributing

We welcome any contributions, from bug reports to new features! If you want to contribute to the package, please read the For Developers section.

If you simply find the package useful, please consider giving it a star ⭐️ on GitHub.

🧑‍💻 For Developers

This section if for advanced users who want to contribute to the package. It will guide you on how to setup the package for development.

Local installation

1. First, clone the repository and install the dependencies:

   git clone https://github.com/arthurdjn/geoserver-py
   cd geoserver-py
   

2. Install the package and the development dependencies with uv

   uv sync
   

[!NOTE] The usual workflow is to create a fork of the repository, clone it, and then install the dependencies.

Testing

First, make sure you have a running GeoServer instance. You can run one using the provided docker-compose file:

docker-compose up -d

Then, you can run the tests using the following command:

make tests

Linting, formatting and typing

You can run the linters, formatters and type checkers using the following command:

make lint     # Run all the below commands
make format   # Format the code using black
make type     # Type check the code using mypy
make isort    # Sort the imports using isort
make all      # Run all the above commands

Before committing

Make sure to run the pre-commit hook before committing, which will check that the formatting, linting and typing are correct:

make pre-commit

[!NOTE] Also make sure the tests are passing.

Once everything is correct, please create a pull request to the repository from your local fork.

About versioning

We follow the Semantic Versioning guidelines for versioning the package. The version number is defined in the pyproject.toml file.

There are some utility commands to automate the versioning and publish associated tags:

make patch    # Bump the patch version
make minor    # Bump the minor version
make major    # Bump the major version

👉 Similar Projects

There are several alternatives to this package, some of them are:

• geoserver-rest is a Python library for management for geospatial data in GeoServer.
• geoserver-restconfig is a python library for manipulating a GeoServer instance via the GeoServer RESTConfig API.

While these packages are great and well-maintained, they do not provide full type hints and customizations over the GeoServer REST API. This library aims to provide a closer API to the GeoServer REST API, making it easier to work with the package.

We would like to thank the authors of these packages for their contributions to the community, which have inspired us to create geoserver-py.