Pin Dependencies

[Alex Robinson]

The Problem

Currently to build the project from the source requires a manual install of the project's dependencies by following Install_Instructions.txt. Consequently pip will download the latest version(s) of the dependencies from PyPI and try and install them.

As time has passed and because Oscar has moved on from maintaining Ortho4XP, the dependencies have been up versioned and certain APIs within them have been deprecated. Now when a user installs the packages they either throw errors or create FutureWarnings when Ortho4XP is run. This is the cause of #126, the import problem with GDAL and is also relevant #149

Proposed Solution

IMO the way to stop this happening in the future is to document the version numbers of the install dependencies, and to edit the install instructions to refer to that file when installing Ortho4XP. AKA pinning dependencies

Doing this will mean that maintainers of Ortho4XP can up version dependencies in a controlled manner. Dealing with any FutureWarnings when and only when they decided to up version.

Also should, for any reason, Ortho4XP fall out of maitenance again, future maintainers will know what dependency version the project last worked on.

Ways of pinning dependencies.

1. requirements.txt

This is the default solution used by Python's inbuilt package manager pip. This is refered to by #158.

Advantages

• Simple install pip install -r requirements.txt
• Simple generation from a given environment pip freeze > requirements.txt

Disadvantages

• Development dependencies are not automatically seperated from build dependencies. Requires manual intervention to keep them seperate. E.g using a seperated requirements-dev.txt
• Dependencies' sub-dependencies are list alongside each requirement.
• Dependency conflicts are not automatically resolved. For example, if one package has the sub dependency numpy<=1.0.0 but we depend on numpy==1.2.3 then pip will install whichever is listed first.
• If no version is explicitly specified for each package in the requirements.txt file, pip simply takes the most recent version.
• Without specifying in the install instructions that a user should create a virtual environment python3 -m venv venv and activate it venv\Scripts\activate.ps1 (Windows) source venv/lib/activate (Mac/Linux) before installing the dependencies will result in all the libraries being installed into the global Python install. This can cause issues.

2. Pipenv

Pipenv is a project that was originally designed to deal with short commings of requirements.txt and pip

Advantages

• Simple install pipenv install
• Creates it's own virtual enviroment before installing
• Automatically traverses the dependency tree and resolves conflicts.
• Stores dependencies in a Pipfile and Pipfile.lock
• Can pin Python version number.
• Seperates build and dev dependencies

Disadvantages

• Pipfile and Pipfile.lock are only used by Pipenv
• Requires the user to install pipenv alongside python

3. Poetry

Poetry (my personal favourite) is another package manager for Python that has been more recently released that Pipenv. This uses the pyproject.toml file defined in PEP-517 to list it's dependencies. This also allows pip to also parse the dependencies and isntall them.

Advantages

• Simple install poetry install
• Creates it's own virtual enviroment before installing
• Automatically traverses the dependency tree and resolves conflicts.
• Stores dependencies in a pyproject.tom and poetry.lock
• Can pin Python version number.
• Seperates build and dev dependencies
• pyproject.toml can also be used by pip
• pyproject.toml is also used by other python libraries and development tools like black, mypy, and isort

Disadvantages

• Requires the user to install poetry alongside python

Closing thoughts

I believe it's very important that Ortho4XP pins it's dependencies. It will help prevent issues in the future and help resolve bugs that currently exist.

If it were purely up to me I would use Poetry. Mainly because that's my personal preference. I've used all of the above methods and strongly feel we should use either Poetry or Pipenv because their advantages vastly outshine using a plain requirements.txt file. I think Poetry just beats Pipenv because of the pyproject.toml support which other libraries also use.

I'm happy to submit a PR to implement this.