Installation

Availability and requirements

The colorspace package is available via the Python Package index (PyPI) or via GitHub.

It has the following requirements.

Additionally, Python’s tkinter interface to Tcl/Tk is leveraged (optional, only used by the interactive palette app). This is typically installed along with the base Python system but might not be available, e.g., on certain Linux distributions. If so, a RuntimeError is raised when invoking the app with some comments for installation.

Installation instructions

The latest release version can be installed from PyPI using:

pip install colorspace

Similarly, the optional requirements (see above) can be installed using:

pip install imageio matplotlib pandas

The latest development version (GitHub head branch) can be installed using:

pip install setuptools # Ensure setuptools installed
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 && pip install setuptools && pip install .

To employ a Python virtual environment, say my_venv, you can initialize and activate it prior to the commands above using:

virtualenv my_venv && source my_venv/bin/activate

Bug reports and feature requests

Please use the GitHub issues to report bugs and feature requests. See the community guidelines for details.

Pull requests or also possible in the GitHub repository. If feasible, it is appreciated when the package’s tests (see below) are run prior to posting a pull request.

Test and development

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

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

# Changing directory
cd python-colorspace

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

# Installing pytest and additional packages as well
# as pytest and setuptools (to ensure both are installed)
pip install -r requirements.txt pytest setuptools

# 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 hard (minimal dependencies) and extended (additional dependencies) tests.

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

# Changing directory
cd python-colorspace

# Creating a fresh `hardvenv` virtual environment and running hard tests only
make hardtest

# Setting up virtual environment with all dependencies for full
# tests as well as for creating the documentation, calculating
# coverage etc., activating venv, installing Python colorspace, and
# running full tests (hard and extended tests)
make venv && source venv/bin/activate && make install && 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

# Changing directory
cd python-colorspace

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

# Activate venv
source venv/bin/activate

# Running tests: Runs 'hard tests' (minimal requirements) first,
# followed by extended tests (with additional requirements)
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