Setting Up Conda to Use Local Bci Essentials Python Source Code

Problem

You want the bci_essentials python package within your conda environment to use the github version of the code on your local machine rather than the pypi version installed through pip install bci_essentials.

More relevant for the developers: You want the package within your conda environment to use the local code you are actively changing for testing and debugging purposes.

tl;dr: See step 4 below.

Solution

Install bci_essentials into your conda environment from your local folder
(i.e. the folder that contains the local git version of the respository).

Use the -e flag (editable) when doing pip install to install the package in editable mode, such that changes made to the source code of the package will immediately affect the installed package. In other words, pip uses the code stored within your local code folder rather than the code it installs within your conda environment folder.

Steps

  1. Create a new conda environment to install a version of bci-essentials-python from your local code (i.e. the folder that contains the local git version of the respository).
  2. A faster step is to clone your existing conda environment you use for bci-essentials-python. > conda create --clone source_env --name new_env
  3. If you clone your existing environment, then uninstall the current version of bci-essentials-python using:

pip uninstall bci_essentials

  1. Activate your new conda environment

conda activate new_env

  1. From within your terminal or command line interface, navigate to the folder hosting your local version of bci-essentials-python (i.e. the folder that contains the local git version of the repository).
  2. Now the main part: To install bci-essentials-python in editable mode so that changes to the source code will immediately affect the installed package, do the following pip command from the root directory of the package:

pip install -e .

  1. (Alternative, non-editable mode) To install bci-essentials-python one-time from the local source code in a way that doesn’t update after further changes to the source code, do the following pip command from the root directory of the package:

pip install .

  1. (Optional) You can use the command pip show bci_essentials to see that the package is using the editable code in your local folder. See the Editable project location in the output of the pip command. E.g.

Editable project location: /Users/anupt/Documents/Work/BCI4Kids/Github/kirtonBCIlab/bci-essentials-python

And voila – now the bci_essentials python package in your conda environment new_env will use your local source code. Thus, changes in the code will be reflected immediately the next time you import or run the package/module.

Considerations

  1. Activate Python kernels: As far as I understand, python kernels that were already activate before the code was changed won’t use the latest version of the local source code. In other words, I think you will need to terminate and relaunch any activate python kernels in order for them to the latest version of your local source code.
  2. Dependencies: If different branches have different dependencies, simply switching branches won’t install or update these dependencies. You might need to manually manage these, depending on the changes between branches.
  3. C Extensions or Compiled Components: If the package has components that need to be compiled (like C extensions), switching branches might not automatically recompile these components. In such cases, after switching branches, you may need to run pip install -e . again to recompile and link the updated components.
  4. Database Migrations, Config Files, etc.: Some packages might also have database migrations, configuration files, or other non-Python code components that might differ between branches. Switching branches might necessitate additional steps to accommodate these changes.