bam-masterdata 0.9.0

The BAM Data Store utility tools and masterdata models wrapped in a Python package with a front-end web interface.

The BAM Masterdata repository contains the masterdata schemas defined at BAM and provides utility functions for working with them.

If you want to install it, do:

pip install bam-masterdata

Development

If you want to develop locally this package, clone the project and enter in the workspace folder:

git clone https://github.com/BAMresearch/bam-masterdata.git
cd bam-masterdata

Create a virtual environment (you can use Python>3.9) in your workspace:

python3 -m venv .venv
source .venv/bin/activate

Run the following script depending on your OS:

• Linux/MacOS:

  ./tools/scripts/install_python_dependencies.sh
  

• Windows:

  tools/scripts/install_python_dependencies.bat
  

Note: This script installs the required dependencies for development, testing, and documentation, using uv and pip.

Run the tests

You can locally run the tests by doing:

python -m pytest -sv tests

where the -s and -v options toggle the output verbosity.

You can also generate a local coverage report:

python -m pytest --cov=src tests

Run auto-formatting and linting

We use Ruff for formatting and linting the code following the rules specified in the pyproject.toml. You can run locally:

ruff check .

This will produce an output with the specific issues found. In order to auto-fix them, run:

ruff format .

If some issues are not possible to fix automatically, you will need to visit the file and fix them by hand.

Pre-commit hooks (recommended)

We use pre-commit to run fast checks automatically on every commit (formatting, linting, secrets scanning, and a repository-specific policy check).

Install once:

pip install pre-commit
pre-commit install

(Optional) Run on the whole repo:

pre-commit run --all-files

Secrets baseline: the repository uses .secrets.baseline. If you add new secrets intentionally (rare), update the baseline:

detect-secrets scan > .secrets.baseline

Documentation on Github pages

To view the documentation locally, make sure to have installed the extra packages (this is part of the tools/scripts/install_python_dependencies.*, so if you ran this script before, you don't need to do it again now):

uv pip install -e '[docu]'

Note: This command installs mkdocs, mkdocs-material, and other documentation-related dependencies.

The first time, build the server:

mkdocs build

Run the documentation server:

mkdocs serve

The output looks like:

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  [14:07:47] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [14:07:47] Serving on http://127.0.0.1:8000/

Simply click on http://127.0.0.1:8000/. The changes in the md files of the documentation are immediately reflected when the files are saved (the local web will automatically refresh).

Main contributors

The main code developers are:

Name	E-mail
Carlos Madariaga	[e-mail]
Lucas Zimmermann	[e-mail]
Dr. Jose M. Pizarro	[e-mail]