# python-owscontext
Python library for OWS request context utility functions.

## Installation

There are two ways two install `owscontext` as a dependency in your application.

### Install using pip (`requirements.txt`)

1. Add `-i https://pypi.theorchard.io/pypi/` to the top of `requirements.txt`.
2. `env/bin/pip install -r requirements.txt`

### Install using Poetry (`pyproject.toml`)

#### pypi.theorchard.com

1. Update `pyproject.toml` to include:

```toml
[[tool.poetry.source]]
name = "pde"
url = "https://pypi.theorchard.io/pypi/"
priority = "supplemental"
```

2. Add this to the `[tool.poetry.dependencies]` section in `pyproject.toml`:
```toml
[tool.poetry.dependencies]
...
owscontext = {version = "^0.1.0", source = "pde"}
```

3. Run `poetry lock`

#### git+ssh

1. Add this to the `[tool.poetry.dependencies]` section in `pyproject.toml`:

```toml
[tool.poetry.dependencies]
...
owscontext = { git = "ssh://git@github.com/theorchard/python-owscontext#v0.1.0"}
```

2. Run `poetry lock`

## Contributing

### Dependencies

This library uses Poetry for dependency management. Please use `poetry add` when adding new dependencies. Always add/commit changes made to the `pyproject.toml` and `poetry.lock` files.

Avoid being overly-restrictive when adding installation requirements. [This](https://packaging.python.org/en/latest/discussions/install-requires-vs-requirements/) has a good overview of considerations when specifying what is required to install owscontext. A few key quotes:

> It’s best practice to indicate any known lower or upper bounds
> It is not considered best practice to use install_requires to pin dependencies to specific versions, or to specify sub-dependencies (i.e. dependencies of your dependencies). This is overly-restrictive, and prevents the user from gaining the benefit of dependency upgrades.

Do indicate if a dependency belongs to development (and thus, not required when the library is installed) using `poetry add <the new dependency> --group dev`.

On a regular basis, run `poetry update` to update to the latest versions of all dependencies in the `poetry.lock` file. Specific dependencies can be updated with `poetry update <the specific dependencies>`.

### `make` targets

You can always use `make help` to view all the documented targets for working in this library. Some common ones are:

```
make env
make lint
make fmt
make test_unit
```

### Packaging/Versioning

Use semver and [Jenkins Pipeline](https://pipeline.theorchard.io/job/publish-pypi-package-v2/) to build/publish new versions of this library to the private PyPI repository at [pypi.theorchard.io](https://pypi.theorchard.io) (currently only available if you are on our VPN).

After a release tag has been pushed to Github, use the Github UI to Create a Release from the tag. Start from the autogenerated notes, and add salient details to the change(s) being added. This will be used by clients of the library to determine what to expect when upgrading (easy vs breaking?).