# Python SpatiaFi API
Python library for interacting with the SpatiaFi API.

Also included is `gdal-auth` which is a CLI tool to help with GCP authentication for GDAL.

## Quickstart

### Install the Package
```shell
pip install spatiafi
```

### Get Authenticated Session
```python
from spatiafi import get_session

session = get_session()
```

### Get help with `gdal-auth`
```shell
gdal-auth --help
```

---

## Development

### Use a Virtual Environment
Development should be done in a virtual environment.
It is recommended to use the virtual environment manager built into PyCharm.
To create a new virtual environment:
  * Open the project in PyCharm and select `File > Settings > Project: spfi-api > Python Interpreter`.
  * In the top right corner of the window, click the gear icon and select `Add Interpreter > Add Local Interpreter...`

### Mark `src` as a Source Root
In PyCharm, mark the `src` folder as a source root. This will allow you to import modules from the `src` folder without using relative imports.
Right-click on the `src` folder and select `Mark Directory as > Sources Root`.

### Bootstrap the Development Environment
Run `./scripts/bootstrap_dev.sh` to install the package and development dependencies.

This will also set up access to our private PyPI server, generate the first `requirements.txt` (if required),
and install `pre-commit` hooks.

**Protip:** This script can be run at any time if you're afraid you've messed up your environment.

### Manage Dependencies in `setup.cfg`
Dependencies are managed in `setup.cfg` using the `install_requires` and `extras_require` sections.

To add a new dependency:
  1. Install the package in the virtual environment with `pip install <package_name>`
  (Hint: use the terminal built in to PyCharm)
  2. Run `pip show <package_name>` to get the package name and version
  3. Add the package name *and version* to `setup.cfg` in the `install_requires` section.
  Use the [compatible release](https://www.python.org/dev/peps/pep-0440/#compatible-release) syntax
  `package_name ~=version`.

**DO NOT** add the package to the `requirements.txt` file. This file is automatically generated by
`scripts/gen_requirements.sh`.

If the dependency is only needed for development, add it to the `dev` section of `extras_require` in `setup.cfg`.

### Building Docker Images Locally
**tl;dr:** run `./scripts/build_docker.sh`.

We need to inject a GCP access token into the Docker build to access private PyPI packages.
This requires using BuildKit (enabled by default in recent versions of Docker), and passing the token as a build
argument.

## `pre-commit` Hooks
This project uses `pre-commit` to run a series of checks before each git commit.
To install the `pre-commit` hooks, run `pre-commit install` in the virtual environment.
(This is done automatically by `./scripts/bootstrap_dev.sh`)

To format all your code manually, run `pre-commit run --all-files`.

**Note:** If your code does not pass the `pre-commit` checks, automatic builds may fail.

### Use `pip-sync` to Update Dependencies
To update local dependencies, run `pip-sync` in the virtual environment.
This will make sure your virtual environment is in sync with the `requirements.txt` file,
including uninstalling any packages that are not in the `requirements.txt` file.

### Versions
The project uses [semantic versioning](https://semver.org/).

Package versions are automatically generated from git tags.
Create your first tag with `git tag 0.1.0` and push it with `git push --tags`

## Installation
**tl;dr:** `./scripts/install_package.sh`

For development, it is recommended to install the package in editable mode with `pip install -e .[dev]`.
