Installation

Installation#

This section describes two type of installation:

We recommend setting up a virtual environment before installing pymascdb.

Virtual Environment Creation#

Although optional, using a virtual environment when installing pymascdb is recommended.

Virtual environments isolate dependencies, simplify package management, improve maintainability, enhance security, and streamline your development workflow.

Below are two options for creating a virtual environment, using venv or conda (recommended).

With conda:

  • Install mamba, miniconda or anaconda if you haven’t already installed.

  • Create a new conda environment (e.g., pymascdb-py311):

conda create --name pymascdb-py311 python=3.11 --no-default-packages

  • Activate the environment:

conda activate pymascdb-py311

With venv:

  • On Windows, create and activate a virtual environment:

python -m venv pymascdb-pyXXX
cd pymascdb-pyXXX/Scripts
activate

  • On macOS/Linux, create and activate a virtual environment:

python3 -m venv pymascdb-pyXXX
source pymascdb-pyXXX/bin/activate

Installation for standard users#

The latest pymascdb stable version is available on the Python Packaging Index (PyPI) and on the conda-forge channel.

Therefore you can either install the package with pip or conda (recommended). Please install the package in the virtual environment you created before !

With conda:

conda install -c conda-forge pymascdb

Note

In alternative to conda, if you are looking for a lightweight package manager you could use micromamba.

With pip:

pip install pymascdb

Installation for contributors#

The latest pymascdb version is available on the GitHub repository pymascdb. You can install the package in editable mode, so that you can modify the code and see the changes immediately. Here below we provide the steps to install the package in editable mode.

Clone the repository from GitHub#

According to the contributors guidelines, you should first create a fork into your personal GitHub account.

Then create a local copy of the repository you forked with:

git clone https://github.com/<your-account>/pymascdb.git
cd pymascdb

Create the development environment#

We recommend to create a dedicated conda environment for development purposes. You can create a conda environment (i.e. with python 3.11) with:

conda create --name pymascdb-dev-py311 python=3.11 --no-default-packages
conda activate pymascdb-dev-py311

Install the package dependencies#

conda install --only-deps pymascdb

Install the package in editable mode#

Install the pymascdb package in editable mode by executing the following command in the pymascdb repository’s root:

pip install -e ".[dev]"

Install code quality checks#

Install the pre-commit hook by executing the following command in the pymascdb repository’s root:

pre-commit install

Pre-commit hooks are automated scripts that run during each commit to detect basic code quality issues. If a hook identifies an issue (signified by the pre-commit script exiting with a non-zero status), it halts the commit process and displays the error messages.

Note

The versions of the software used in the pre-commit hooks is specified in the .pre-commit-config.yaml file. This file serves as a configuration guide, ensuring that the hooks are executed with the correct versions of each tool, thereby maintaining consistency and reliability in the code quality checks.

Further details about pre-commit hooks can be found in the Contributors Guidelines, specifically in the provided in the Code quality control section.

Optional dependencies#

Specific functionality in pymascdb may require additional optional dependencies. To unlock the full functionalities offered by pymascdb, it is recommended to install also the packages detailed here below.

IDEs#

For an improved development experience, consider installing the intuitive Jupyter and Spyder Python Integrated Development Environments (IDEs):

conda install -c conda-forge jupyter spyder

Speed Up Xarray Computations#

To speed up arrays computations with xarray, install flox, numbagg, bottleneck and opt-einsum:

conda install -c conda-forge flox numbagg bottleneck opt-einsum

Analyze MASCDB data on Jupyter Notebooks#

If you want to run pymascdb on a Jupyter Notebook, you have to take care to set up the IPython kernel environment where pymascdb is installed.

For example, if your conda/virtual environment is named pymascdb-dev, run:

python -m ipykernel install --user --name=pymascdb-dev

When you will use the Jupyter Notebook, by clicking on Kernel and then Change Kernel, you will be able to select the pymascdb-dev kernel.