Basics

To begin, let’s get the code:

$ git clone https://github.com/cognitedata/cognite-python-utils.git
$ cd cognite-python-utils

Managing Dependencies

The current project uses poetry to manage dependencies among different Python packages, which is essential to reproducibility.

First, ensure you are using the right version of Python (^3.8). We recommend you use pyenv to effectively manage multiple versions of Python installation. You can then install poetry:

$ pip install poetry

Once you clone the project repo, go to its root and run:

$ poetry install

to install correct dependencies for the project.

To activate the virtual environment, run:

$ poetry shell

To add a new dependency, run:

$ poetry add <new-package-name>

Finally, you can type:

$ exit

to exit from the virtual environment.

Running Pre-Commit Hooks

Consistent coding standards enable effective code review and maintenance. Hence, we strongly recommend you use pre-commit hooks set for the project. You can install them by running:

$ pre-commit install

Then, whenever you are about to make a new commit, run:

$ pre-commit run --all-files

to automatically apply coding standards set for the project.

Unit Testing

Each utility should come with unit tests to ensure usable code beyond dependency updates. Hence, we strongly recommend you use pytest standards for each utility. You can find example unit tests in the .tests/tests_unit directory.

Implement unit tests with a new file per utility, with monkeypatch_cognite_client() where necessary.

Then, whenever you are about to make a new commit, run:

$ pytest -v tests

Updating Project Documentation

The current project’s documentation is generated using Sphinx and hosted on GitHub Pages. To update it, make changes in docs-source directory and run:

$ cd docs-source
$ make clean
$ make html
$ cp -r ./build/html/* ../docs

which will update build artifacts used by GitHub Pages.

Warning

Note: If making documents for the first time, the Jupyter notebooks require Pandoc to make the html documentation. To install Pandoc on your local machine, see https://pandoc.org/installing.html

Warning

When adding demo Jupyter notebooks, please ensure that the outputs do not include any confidential information such as customer identity. To this aim, we recommend you use fictitious data for running your notebooks. If you have no choice but use customer data to run the notebooks, please ensure to redact/replace any confidential information from outputs.