https://github.com/arthurdjn/geoserver-py
Unofficial GeoServer python client. Manage workspaces, permissions, upload vectors, rasters and more.
https://github.com/arthurdjn/geoserver-py
api client geoserver geospatial gis ogc python rasters requests rest vectors
Last synced: about 1 year ago
JSON representation
Unofficial GeoServer python client. Manage workspaces, permissions, upload vectors, rasters and more.
- Host: GitHub
- URL: https://github.com/arthurdjn/geoserver-py
- Owner: arthurdjn
- License: mit
- Created: 2024-06-05T22:53:10.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-07T16:45:53.000Z (about 1 year ago)
- Last Synced: 2025-04-07T17:42:28.381Z (about 1 year ago)
- Topics: api, client, geoserver, geospatial, gis, ogc, python, rasters, requests, rest, vectors
- Language: Jupyter Notebook
- Homepage: https://arthurdjn.github.io/geoserver-py/
- Size: 1.99 MB
- Stars: 16
- Watchers: 1
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://www.python.org/)
[](https://docs.astral.sh/ruff)
[](https://mypy-lang.org)
[](https://python-poetry.org)
[](https://pytest.org)
______________________________________________________________________
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](https://arthurdjn.github.io/geoserver-py)**. 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
```python
# As JSON
workspaces = geoserver.get_workspaces() # default is "json"
# As XML
workspaces = geoserver.get_workspaces(format="xml")
```
#### Post requests
```python
# As JSON
geoserver.create_workspace(body={"workspace": {"name": "new_workspace"}})
# As XML
geoserver.create_workspace(body="new_workspace")
```
### Documentation
We provide several [examples](./notebooks) and a [documentation](https://arthurdjn.github.io/geoserver-py) to help you get started,
## 🚀 Quick Start
This section will guide you on how to setup and use the package.
### Installation
```bash
pip install geoserver-py
```
### Usage
```python
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](./notebooks) folder. These examples are based on the [GeoServer REST API documentation](https://docs.geoserver.org/main/en/user/rest/index.html).
## 🤗 Contributing
We welcome any contributions, from bug reports to new features! If you want to contribute to the package, please read the [For Developers](#-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:
```bash
git clone https://github.com/arthurdjn/geoserver-py
cd geoserver-py
```
1. Install the dependencies (we recommend using [`poetry`](https://python-poetry.org/) for this)
```bash
poetry install
```
> \[!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:
```bash
docker-compose up -d
```
Then, you can run the tests using the following command:
```bash
make tests
```
### Linting, formatting and typing
You can run the linters, formatters and type checkers using the following command:
```bash
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:
```bash
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](https://semver.org/) 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:
```bash
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`](https://github.com/gicait/geoserver-rest) is a Python library for management for geospatial data in GeoServer.
- [`geoserver-restconfig`](https://github.com/GeoNode/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`._