Developer Installation
This is a companion document to the contributor guidelines.
A developer installation of ObsPy will recognize any changes you make locally to the code base. For this you need to install all dependencies of ObsPy. A very easy way to do this -- and thus highly recommended in may cases -- is to first install ObsPy with Anaconda in a dedicated, new environment and then remove the ObsPy package again, leaving the dependencies installed.
Please note: When working in an editable installation and making changes to either any C source code files or making changes to the plugin system (ENTRY_POINTS in setup.py), you need to subsequently refresh the editable pip installation (do $ pip install -v -e /path/to/obspy again) for changes to take effect.
The easiest easy way to get a working developer installation of ObsPy is via Anaconda. First install the prebuilt, stable ObsPy release package in a fresh, dedicated environment and then just remove ObsPy again - this will leave all dependencies installed (see here for more details regarding an installation with conda). Example (feel free to use a different environment name):
# "git" package not needed if already installed in the system
# "c-compiler" package may not be needed if system has a proper C compiler setup
(base) $ conda create -n obspy_dev -c conda-forge python=3.7 obspy git c-compiler pytest pytest-json-report
(base) $ conda activate obspy_dev
(obspy_dev) $ conda uninstall --offline --force obspy # Uninstall without removing dependenciesYou then want to checkout ObsPy locally with git*. You also need a C compiler for the subsequent compilation (should be properly set up by the activated Anaconda environment).
*) N.b.: Making an editable install from an unpacked tarball (as opposed to a git repository clone)
is possible in the same way, but it lacks the option to output a diff of changes made locally,
so it is not advisable for a developer installation.
Install obspy in pip's "editable" mode
(obspy_dev) $ cd /directory/where/code/lives
# Clone your own ObsPy fork!
(obspy_dev) $ git clone https://github.com/YOUR_USERNAME/obspy.git
(obspy_dev) $ cd obspy
# Make sure you branch from the correct base branch! See the
# contributor guidelines for rules on how to choose the correct
# base branch.
(obspy_dev) $ git checkout master # Might be different for you
# Make a new branch with your changes.
(obspy_dev) $ git checkout -b my-new-features # Choose a sensible branch name!
# Change into the conda env created for this purpose above (if it is not yet activated):
# "$ conda activate obspy_dev"
# The `-e` will only copy a kind of symlink to the `site-packages`
# directory of your activate Python installation. So any changes you
# make to the code base will be reflected when you actually run ObsPy.
# You'll have to rerun this command any time a C source code file or
# entry points of the plugin system in `setup.py` were changed.
(obspy_dev) $ pip install -v -e .Alternatively to the above, if there is no need to make trackable changes, there is also the option to install a certain branch of ObsPy in that environment (after the initial setup and then removal of the obspy package only shown above):
(obspy_dev) $ pip install https://github.com/obspy/obspy/archive/refs/heads/fix_resp_complex_uncertainties.zipThis example installs the branch of pull request #3412. To get that zip URL, on a pull request page on github, click on the head branch link (at the top: " wants to merge commits into from ") and on the following page of that branch click on "Code" and copy the link of the "Download Zip" button.
N.b.: The version number can not be properly resolved for obspy when installing such a zip file, so conda will show something like "0.0.0-dev" as version number for your obspy installed version.
You should consider using the Anaconda approach above, if at all feasible. Not using Anaconda is for experienced developers familiar with e.g. C compiler setup. You will need a Python 3 installation with the following in place before installing ObsPy with pip editable mode as shown in the above section:
- pip
- numpy
- C compiler
- git (optional, making an editable installation from an unpacked tar/zipball is possible but much less convenient to track changes made locally or to prepare Pull requests)
