Package Installation

This package is available via the Python Package index (PyPI) or via GitHub. A few requirements are needed to be able to use the package and all its features.

Python, tested for versions 3.8, 3.9, 3.10, 3.11, 3.12)
numpy
matplotlib (optional; used for visualization)
imageio (optional; only used by cvd_image())
pandas (optional; used by dataset())

Please use the GitHub issues to report bugs and issues as well as feature requests. There is no guarantee that feature requests can be accommodated, especially as we try to keep both, the R and Python version of the package, around the same level.

Installation

The latest release can be directly installed from PyPI using:

pip install colorspace

… or installing the last version (GitHub head branch) using:

pip install git+https://github.com/retostauffer/python-colorspace

Alternatively, clone the git repository and install the package from there:

git clone https://github.com/retostauffer/python-colorspace.git
cd python-colorspace && python setup.py install

Using a virtual environment

Alternatively, a Python virtual environment can be used. The additional (optional) packages allow to use full colorspace functionality, but are optional and not required by most core features.

# Initialize and activate new virtual env
virtualenv my_venv && source my_venv/bin/activate

# Installing colorspace
pip install colorspace

# Installing additional (optional) packages
pip install imageio matplotlib pandas

Test and development

The following sections are intended for developers, not for users, and gives some insights on how to run automated tests, create coverage reports, test examples, and render the documentation.

If you encounter issues and bugs, or are interested to contribute to the Python colorspace package, please read our Community guidelines.

Testing

To run the automated tests with minimal requirements, we suggest to clone the repository, set up a virtual environment with the required packages, and then run the test using pytest.

# Cloning current main branch
git clone https://github.com/retostauffer/python-colorspace.git

# Setting up and activating virtual environment
virtualenv my_venv
source my_venv/bin/activate

# Installing pytest and additional packages + pytest
pip install -r requirements.txt pytest

# Installing Python colorspace (from current main branch)
pip install -e .

# Run tests
pytest

For those using the GNU make utility, the package comes with a Makefile which includes rules for running soft (minimal dependencies) and extended (additional dependencies) tests.

# Cloning current main branch
git clone https://github.com/retostauffer/python-colorspace.git

# Creates a fresh `softvenv` virtual environment and runs soft tests
make softtest

# Setting up virtual environment with all dependencies for full
# tests as well as for creating the documentation, calculating
# coverage etc., install Python colorspace, activate venv and
# run full tests.
make venv && make install && source venv/bin/activate && make test

Development

For the developers out there, the Makefile provides additional rules for creating/updating the man pages, creating the coverage report, testing the docstring examples, and rendering the documentation. Note that the latter two require quarto to be installed.

# Cloning current main branch
git clone https://github.com/retostauffer/python-colorspace.git

# Setting up virtualenv, installing colorspace (main)
make venv && make install

# Activate venv
source venv/bin/activate

# Running tests (runs 'soft tests' first)
make test

# Create coverage report; tries to open report in firefox
make cov

# Testing docstring examples; requires pyp2qmd and quarto
make examples

# Building documentation; requires pyp2qmd and quarto
make render