Cast single-band Raster to 2D

.coveragerc

@@ -0,0 +1,5 @@
+[report]
+exclude_lines =
+    pragma: not covered
+    @overload
+    except ImportError

.github/workflows/python-app.yml

@@ -48,7 +48,7 @@ jobs:
         path: ${{ env.CONDA }}/envs
         key: conda-${{ matrix.os }}-${{ matrix.python-version }}-${{ steps.get-date.outputs.month }}-${{ hashFiles('dev-environment.yml') }}-${{ env.CACHE_NUMBER }}
       env:
-        CACHE_NUMBER: 5 # Increase this value to reset cache if environment.yml has not changed
+        CACHE_NUMBER: 102 # Increase this value to reset cache if environment.yml has not changed
       id: cache
 
     # The trick below is necessary because the generic environment file does not specify a Python version, and only
@@ -79,7 +79,7 @@ jobs:
         pkgs_pip_dev=`python -c "import geoutils; geoutils.misc.diff_environment_yml('environment.yml', 'dev-environment.yml', 'pip')"`
         mamba install $pkgs_conda_dev --freeze-installed
         if [[ "$pkgs_pip_dev" != "None" ]]; then
-          pip install $pkgs_pip_dev
+          pip install --user $pkgs_pip_dev
         fi
 
     # Stop the build if there are Python syntax errors or undefined names

.gitignore

@@ -141,8 +141,17 @@ geoutils/version.py
 # End of https://www.gitignore.io/api/python
 .vim/
 doc/source/file.txt
-doc/source/auto_examples/
+doc/source/io_examples/
+doc/source/handling_examples/
+doc/source/analysis_examples/
 doc/source/gen_modules/
 
 # Directories where example data is downloaded
 examples/data/
+
+# Directory where myst_nb executes jupyter code
+doc/jupyter_execute/
+
+# Files that should have been deleted by Sphinx at end of build (but can exist if build fails)
+examples/io/open_save/myraster.tif
+examples/io/open_save/myvector.gpkg

.pre-commit-config.yaml

@@ -16,7 +16,7 @@ repos:
                   types_or: [python, rst, markdown]
                   files: ^(geoutils|doc|tests)/
 
-        # Replace relative imports (e.g. 'from . import georaster' -> 'from geoutils import georaster')
+        # Replace relative imports (e.g. 'from . import raster' -> 'from geoutils import raster')
         - repo: https://github.com/MarcoGorelli/absolufy-imports
           rev: v0.3.1
           hooks:
@@ -44,7 +44,7 @@ repos:
                   files: ^(geoutils|tests)
         # Lint the code using mypy
         - repo: https://github.com/pre-commit/mirrors-mypy
-          rev: v0.982
+          rev: v1.1.1
           hooks:
                 - id: mypy
                   args: [
@@ -54,12 +54,12 @@ repos:
                         --show-error-codes,
                         --no-warn-unused-ignores,  # Ignore 'type: ignore' comments that are not used.
                         --disable-error-code=attr-defined,  # "Module has no attribute 'XXX'" occurs because of the pre-commit env.
-                        --disable-error-code=name-defined  # "Name 'XXX' is not defined" occurs because of the pre-commit env.
-
+                        --disable-error-code=name-defined,  # "Name 'XXX' is not defined" occurs because of the pre-commit env.
+                        --disable-error-code=var-annotated,
+                        --disable-error-code=no-any-return
                   ]
                   additional_dependencies: [tokenize-rt==3.2.0]
-
-
+                  files: ^(geoutils|tests)
 
         # Sort imports using isort
         - repo: https://github.com/PyCQA/isort

.readthedocs.yml → .readthedocs.yaml

@@ -5,6 +5,11 @@
 # Required
 version: 2
 
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "mambaforge-4.10"
+
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: doc/source/conf.py
@@ -13,9 +18,6 @@ sphinx:
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: []
 
-python:
-  version: 3.8
-  install:
-    - requirements: dev-requirements.txt
-    - method: pip
-      path: .
+
+conda:
+  environment: dev-environment.yml

CONTRIBUTING.md

@@ -1,103 +1,53 @@
 # How to contribute
 
 ## Overview: making a contribution
+
 For more details, see the rest of this document.
 
-1. Fork and clone the repository.
-2. Set up the development environment.
+1. Fork _GlacioHack/geoutils_ and clone your fork repository locally.
+2. Set up the development environment (section below).
 3. Create a branch for the new feature or bug fix.
-4. Make your changes, ensuring they are conventions-compliant.
+4. Make your changes, and add or modify related tests in _tests/_.
 5. Commit, making sure to run `pre-commit` separately if not installed as git hook.
-6. Push.
-7. Open a Pull Request to discuss and eventually merge.
-8. You can now delete your feature branch.
-
-
-## Rights
-The license (see LICENSE) applies to all contributions.
-
-
-## Issue Conventions
-When submitting bugs, please fill out the bug report template in full.
-
-Please search existing issues, open and closed, before creating a new one.
-
-
-## Git conventions
-Work on features should be made on a fork of `geoutils` and submitted as a pull request (PR) to master or a relevant branch.
-
-
-## Code conventions
-
-Contributors of `geoutils` should attempt to conform to pep8 coding standards.
-An exception to the standard is having a 120 max character line length (instead of 80).
-
-Suggested linters are:
-1. prospector
-2. mypy (git version)
-3. pydocstyle
-
-Suggested formatters are:
-1. autopep8
-2. isort
-
-## Test conventions
-At least one test per feature (in the associated `tests/test_*.py` file) should be included in the PR, but more than one is suggested.
-We use `pytest`.
-
+6. Push to your fork.
+7. Open a pull request from GitHub to discuss and eventually merge.
 
 ## Development environment
-We target Python 3 or higher for `geoutils`.
-Some features may require later versions of Python (3.6+) to function correctly.
 
+GeoUtils currently supports only Python versions of 3.8 and higher, see `environment.yml` for detailed dependencies.
 
 ### Setup
 
-Clone the git repo and create a conda environment:
+Clone the git repo and create a `mamba` environment (see how to install `mamba` in the [mamba documentation](https://mamba.readthedocs.io/en/latest/)):
 
 ```bash
 git clone https://github.com/GlacioHack/geoutils.git
 cd geoutils
-conda env create -f environment.yml  # add '-n custom_name' if you want.
-conda activate geoutils  # or any other name specified above
-pip install -e .  # Install geoutils in developer mode
+mamba env create -f dev-environment.yml  # Add '-n custom_name' if you want.
+mamba activate geoutils-dev  # Or any other name specified above
 ```
 
-Now install the additional development dependencies:
-```bash
-pip install -r dev-requirements.txt
-```
-
-Finally, we also recommend installing the formatting and linting tools listed above to help with adhering to code conventions:
-```bash
-pip install prospector git+https://github.com/python/mypy.git pydocstyle autopep8 isort
-```
-
-Note that your text editor of choice will also need to be configured with these tools (and max character line length changed to 120).
+### Tests
 
+At least one test per feature (in the associated `tests/test_*.py` file) should be included in the PR, using `pytest` (see existing tests for examples).
 
-### Running the tests
 To run the entire test suite, run `pytest` in the current directory:
 ```bash
 pytest
 ```
 
-It is also recommended to try the tests from the parent directory, to validate that import statements work as they should:
-```bash
-cd ../  # Change to the parent directory
-pytest geoutils
-```
-
 ### Formatting and linting
-To merge a PR in geoutils, the code has to adhere to the standards set in place.
-We use a number of tools to validate contributions, triggered using `pre-commit` (see `.pre-commit-config.yaml` for the exact tools).
 
-`pre-commit` is made to be installed as a "pre-commit hook" for git, so the checks have to pass before committing. Before committing for the first time, you need to install the hook:
-```bash
-pre-commit install
-```
+Install and run `pre-commit` (see [pre-commit documentation](https://pre-commit.com/)), which will use `.pre-commit-config.yaml` to verify spelling errors,
+import sorting, type checking, formatting and linting.
 
-Pre-commit can also be run as a separate tool:
+You can then run pre-commit manually:
 ```bash
 pre-commit run --all-files
 ```
+
+Optionally, `pre-commit` can be installed as a git hook to ensure checks have to pass before committing.
+
+## Rights
+
+The license (see LICENSE) applies to all contributions.

README.md

@@ -1,5 +1,4 @@
-# geoutils
-Set of tools to handle raster and vector data sets in Python.
+# GeoUtils: consistent geospatial analysis in Python.
 
 ![](https://readthedocs.org/projects/geoutils/badge/?version=latest)
 [![build](https://github.com/GlacioHack/geoutils/actions/workflows/python-app.yml/badge.svg)](https://github.com/GlacioHack/GeoUtils/actions/workflows/python-app.yml)
@@ -9,51 +8,42 @@ Set of tools to handle raster and vector data sets in Python.
 [![PyPI version](https://badge.fury.io/py/geoutils.svg)](https://badge.fury.io/py/geoutils)
 [![Coverage Status](https://coveralls.io/repos/github/GlacioHack/geoutils/badge.svg?branch=main)](https://coveralls.io/github/GlacioHack/geoutils?branch=main)
 
-This package offers Python classes and functions as well as command line tools to work with both geospatial raster and vector datasets. It is built upon rasterio and GeoPandas. In a single command it can import any geo-referenced dataset that is understood by these libraries, complete with all geo-referencing information, various helper functions and interface between vector/raster data.
+[![Pre-Commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+[![Formatted with black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
+[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/)
 
+**GeoUtils** is an open source project to develop a core Python package for geospatial analysis and foster inter-operability between other Python GIS packages.
 
-## Installation
-
-#### With conda (recommended)
-```bash
-conda install --channel conda-forge --strict-channel-priority geoutils
-```
-The `--strict-channel-priority` flag seems essential for Windows installs to function correctly, and is recommended for UNIX-based systems as well.
+It aims at **facilitating end-user geospatial analysis by revolving around consistent `Raster` and `Vector` objects** that effortlessly interface between
+themselves. GeoUtils is founded on **implicit loading behaviour**, **robust numerical interfacing** and **convenient object-based methods** to easily perform
+the most common higher-level tasks needed by geospatial users.
 
-#### With pip
-
-From PyPI:
-```bash
-pip install geoutils
-```
+If you are looking for an accessible Python package to write the Python equivalent of your [GDAL](https://gdal.org/) command lines, or of your
+[QGIS](https://www.qgis.org/en/site/) analysis pipeline **without a steep learning curve** on Python GIS syntax, GeoUtils is perfect for you! For more advanced
+users, GeoUtils also aims at being efficient and scalable by supporting lazy loading and parallel computing (ongoing).
 
-Or from the repository tarball: make sure GDAL and PROJ are properly installed, then:
-```bash
-pip install https://github.com/GlacioHack/geoutils/tarball/main
-```
+GeoUtils relies on [Rasterio](https://github.com/rasterio/rasterio), [GeoPandas](https://github.com/geopandas/geopandas) and [Pyproj](https://github.com/pyproj4/pyproj) for georeferenced
+calculations, and on [NumPy](https://github.com/numpy/numpy) and [Xarray](https://github.com/pydata/xarray) for numerical analysis. It allows easy access to
+the functionalities of these packages through interfacing or composition, and quick inter-operability through object conversion.
 
 ## Documentation
-See the full documentation at https://geoutils.readthedocs.io.
-
-
-## Structure
 
-GeoUtils is composed of three libraries:
-- `georaster.py` to handle raster data set. In particular, a Raster class to load a raster file along with metadata.
-- `geovector.py` to handle vector data set. In particular, a Vector class to load a raster file along with metadata.
-- `projtools.py` with various tools around projections.
+For installation, quick start, gallery examples, a full feature description or a search through the API, see GeoUtils' documentation at:
+https://geoutils.readthedocs.io.
 
+## Installation
 
-## How to contribute
+```bash
+mamba install -c conda-forge geoutils
+```
 
-You can find ways to improve the libraries in the [issues](https://github.com/GlacioHack/geoutils/issues) section. All contributions are welcome.
+See [mamba's documentation](https://mamba.readthedocs.io/en/latest/) to install `mamba`, which will solve your environment much faster than `conda`.
 
-1. Fork the repository to your personal GitHub account, clone to your computer.
-2. (Optional but preferred:) Make a feature branch.
-3. Push to your feature branch.
-4. When ready, submit a Pull Request from your feature branch to `GlacioHack/geoutils:master`.
-5. The PR will be reviewed by at least one other person. Usually your PR will be merged via 'squash and merge'.
+## Start contributing
 
-Direct pushing to the GlacioHack repository is not permitted.
+1. Fork the repository, make a feature branches and push changes.
+2. When ready, submit a pull request from the feature branch of your fork to `GlacioHack/geoutils:master`.
+3. The PR will be reviewed by at least one maintainer, discussed, then merged.
 
-A more detailed contribution instruction [can be found here](CONTRIBUTING.md).
+More info on [our contributing page](CONTRIBUTING.md).