Skip to content

Development environment setup

  1. Fork nsidc/earthaccess
  2. Clone your fork (git clone git@github.com:{my-username}/earthaccess)

earthaccess uses Poetry to build and publish the package to PyPI, the defacto Python repository. In order to develop new features or fix bugs etc. we need to set up a virtual environment and install the library locally. We can accomplish this with Conda and Poetry, or just with Poetry. Both workflows achieve the same result.

Using Conda

If we have mamba (or conda) installed, we can use the environment file included in the ci folder. This will install all the libraries we need (including Poetry) to start developing earthaccess:

mamba env update -f ci/environment-dev.yml
mamba activate earthaccess-dev
poetry install

After activating our environment and installing the library with Poetry we can run Jupyter lab and start testing the local distribution or we can use make to run the tests and lint the code. Now we can create a feature branch and push those changes to our fork!

Using Poetry

If we want to use Poetry, first we need to install it. After installing Poetry we can use the same workflow we used for Conda, first we install the library locally:

poetry install

and now we can run the local Jupyter Lab and run the scripts etc. using Poetry:

poetry run jupyter lab

Note

You may need to use poetry run make ... to run commands in the environment.

Managing Dependencies

If you need to add a new dependency, you should do the following:

  • Run poetry add <package> for a required (non-development) dependency
  • Run poetry add --group=dev <package> for a development dependency, such as a testing or code analysis dependency

Both commands add an entry to pyproject.toml with a version that is compatible with the rest of the dependencies. However, poetry pins versions with a caret (^), which is not what we want. Therefore, you must locate the new entry in pyproject.toml and change the ^ to >=. (See poetry-relax for the reasoning behind this.)

In addition, you must also add a corresponding entry to ci/environment-mindeps.yaml. You'll notice in this file that required dependencies should be pinned exactly to the versions specified in pyproject.toml (after changing ^ to >= there), and that development dependencies should be left unpinned.

Finally, for development dependencies only, you must add an entry to ci/environment-dev.yaml with the same version constraint as in pyproject.toml.