Contributing
Project setup
In case you want to play with the source code or contribute changes proceed as follows:
Check out the project from GitHub:
$ git clone https://github.com/roskakori/pimdb.git $ cd pimdb
Create and activate a virtual environment:
$ python -m venv venv $ . venv/bin/activate
Install the required packages:
$ pip install --upgrade pip $ pip install -r requirements.txt
Install the pre-commit hook:
$ pre-commit install
Testing
To run the test suite:
$ pytest
To build and browse the coverage report in HTML format:
$ pytest --cov-report=html
$ open htmlcov/index.html # macOS only
- PIMDB_TEST_DATABASE
By default, all database related tests run on SQLite. Some tests can run on
different databases in order to test that everything works across a wide
range. To use a specific database, set the respective engine in the
environment variable PIMDB_TEST_DATABASE. For example:
export PIMDB_TEST_DATABASE="postgresql+psycopg2://postgres@localhost:5439/pimdb_test"
- PIMDB_TEST_FULL_DATABASE
Some tests require a database built with actual full datasets instead of just
small test datasets. Use the environment variable
PIMDB_TEST_FULL_DATABASE to set it. For example:
export PIMDB_FULL_TEST_DATABASE="sqlite:////Users/me/Development/pimdb/pimdb.db"
Test run with PostgreSQL
While the test suite uses SQLite, you can test run pimdb on a PostgreSQL database in a docker container:
Install Docker Desktop
Run the postgres container in port 5439 (possibly using sudo):
docker-compose --file tests/docker-compose.yml up postgres
Create the database (possibly using sudo):
docker exec -it pimdb_postgres psql --username postgres --command "create database pimdb"
If you want a separate database for the unit tests:
docker exec -it pimdb_postgres psql –username postgres –command “create database pimdb_test”
Run pimdb:
pimdb transfer --dataset-folder tests/data --database postgresql+psycopg2://postgres@localhost:5439/pimdb all
Documentation
To build the documentation in HTML format:
$ make -C docs html
$ open docs/_build/html/index.html # macOS only
Coding guidelines
The code throughout uses a natural naming schema avoiding abbreviations, even for local variables and parameters.
Many coding guidelines are automatically enforced (and some even fixed automatically) by the pre-commit hook. If you want to check and clean up the code without performing a commit, run:
$ pre-commit run --all-files