This repo structure has been autogenerated from Intellectual Labs cookiecutter template.

factorymind

Python module factorymind for the FactoryMind platform

• factorymind
  • Setup
    • Installation issues
    • Precommit
      • Usage
  • Testing
  • Publish Package
    • Bumpversion
  • Documentation
  • General references

Setup

The setup shows how to set up your environment with the poetry python package manager.

1. Install git and checkout the git code repository.

2. Install [Poetry]: https://python-poetry.org/docs/#installation

3. Change working directory into the git code repository root

4. Create the self contained environment;

   • (If the config file pyproject.toml does not exist, initialize the environment file poetry init.)
   • Create the env poetry install
   • Activate poetry shell poetry shell
   • Add packages by poetry add <package>.
     • add package as dev package --dev (-D), e.g. poetry add -D ipykernel (already included)
     • install without dev dependencies poetry install --no-dev
   • Update poetry.lock without upgrading dependencies: poetry lock --no-update

Installation issues

• If you have any issues installing any python packages
  • especially wheels, try to update pip: pip install --upgrade pip
  • Or try upgrading your poetry version: poetry self update

Precommit

• pip install pre-commit (already installed in poetry env by default)
• Install the git hook scripts in .pre-commit-config.yaml:

  pre-commit install
  

• detect secrets setup
  • detect-secrets scan > .secrets.baseline
• auto update: pre-commit autoupdate

Usage

• pre-commit run --all-files

Testing

Reproducability and the correct functioning of code are essential to avoid wasted time. If a code block is copied more than once then it should be placed into a common script / module under src/ and unit tests added. The same applies for any other non trivial code to ensure the correct functioning.

To run tests, ensure you have installed the conda environment as explained above (from conda_env.yml) and activated it. If not, install pytest, pytest-cookies, pytest-cov, pytest-remotedata==0.3.2 using pip or conda. Then from the repository root run

pytest tests\

To display test coverage of all source code in the folder src/ run from repository root

pytest --cov-report term-missing --cov=src tests/

For more details, see the README in the folder tests\.

Publish Package

• poetry build
• poetry publish
  • Use token: https://pypi.org/help/#apitoken
  • poetry config pypi-token.pypi my-token (would be optimal to use the .pypirc file, but currently not able to use that in a nice way with poetry)

Bumpversion

0. Setup bumpver
   1. poetry add bumpver
   2. bumpver init
1. Bump version and commit
   1. bumpver update --patch

Documentation

This project use Sphinx for documentation with auto-documentation for the Python package source code in .src/. The documentation files are located in ./docs/writeup/.

To update the documentation, go to (cd into) ./docs/writeup/ and run

sphinx-apidoc -f -e -o source ../../src/factorymind
make html

This will auto-document content in ./src/factorymind/, forcing overwrite of existing doc files (flag -f) putting docs for each submodule in seperate pages (flag -e) and placing the .rst doc files in ./docs/writeup/source/ (flag -o). View the updated docs by opening ./docs/writeup/_build/html/index.html in your web browser.

References:

• General Sphinx docs
• Pythons Developers Guide for how to properly documenting Python code with rst and an example sphinx docstring
• Sphinx themes, and in particular docs for customizing the alabaster theme
• Using sphinx-apidoc to auto-generate doc files.

General references

• https://github.com/IntellectualLabs/data_science_template
• http://docs.python-guide.org/en/latest/writing/structure/
• https://factorymind.ai/