Merge pull request #46 from Excidion/task-runner

Justfile for task definitions

Author: Excidion

.gitignore

@@ -26,6 +26,6 @@ __pycache__/
 # uv
 .venv
 
-# ctt
+# testing ctt and mkdocs build
 .ctt
-ctt.toml
+test

README.md

@@ -53,6 +53,8 @@ Depending on your choices, it will generate a structure that looks something lik
 │
 ├── pyproject.toml     <- Project configuration and dependencies.
 │
+├── justfile           <- Useful commands
+│
 └── README.md          <- The top-level README for developers using this project.
 ```
 For more details check out the [documentation](https://excidion.github.io/reproML/structure/).

constants.yml

@@ -20,14 +20,10 @@ md_project_setup:
     ```
     {%- endif %}
     Navigate to the project directory and install all dependencies:
+    ```bash
+    ./just.sh install
     ```
-    uv sync --all-groups --all-extras
-    ```
-    This command will also create a virtual environment for the project.
-    To make sure that pre-commits are enabled run:
-    ```
-    uv run pre-commit install --hook-type pre-push --hook-type post-checkout --hook-type pre-commit
-    ```
+    This will also enable pre-commit hooks.
     {%- if use_dvc %}
     And make sure that you have all the necessary data available.
     ```

ctt.toml

@@ -0,0 +1,10 @@
+[defaults]
+project_name = "A new Project"
+project_description = "Not much."
+author = "Excidion"
+author_email = "36995046+Excidion@users.noreply.github.com"
+ci = ""
+
+[output.".ctt/test"]
+python_version = "3.10"
+use_dvc = false

justfile

@@ -0,0 +1,16 @@
+install:
+    uv sync --all-groups --all-extras
+    uv run pre-commit install --hook-type pre-push --hook-type post-checkout --hook-type pre-commit
+
+hooks:
+    uv run pre-commit run --all-files
+
+docs:
+    uv run mkdocs build --strict --site-dir test
+    rm -rf test
+
+test:
+    uv run ctt
+    rm -rf .ctt
+
+check: install hooks docs test

pyproject.toml

@@ -16,6 +16,7 @@ dependencies = [
     "mkdocs-literate-nav>=0.6.1",
     "mkdocs-material>=9.5.35",
     "mkdocstrings[python]>=0.26.1",
+    "rust-just>=1.46.0",
 ]
 
 [dependency-groups]

reproML/README.md.jinja

@@ -11,5 +11,5 @@ For more details take look at the [documentation](#look-at-the-documentation)
 For more detailed information about the project check out the documentation.
 Use the following command to run the documentation webserver.
 ```
-uv run mkdocs serve
+just docs
 ```

reproML/docs/structure.md

@@ -134,6 +134,8 @@ This is your first overview how to find your way around this project.
 ├── pyproject.toml     <- Project configuration and dependencies.
 ├── uv.lock            <- Full dependency list. Managed by uv, do not touch.
 │
+├── justfile           <- Useful commands
+│
 └── README.md          <- The top-level README for developers using this project.
 ```
 All folders marked with `<dvc>` are versioned via dvc and so are their subfolders.
@@ -334,17 +336,13 @@ def main():
     model = 42
     save_model(model, "model")
 
-
-if __name__ == "__main__":
-    main()
-
 ```
 Using this will automatically log the start and end of every function you decorate with it.
 Depening on the log level, you'll even be able to trace arguments and return values.
 ```bash
-$ uv run src/model/train.py
-# 2038-01-19 03:14:08,000 INFO    __main__.main START
-# 2038-01-19 03:14:08,001 DEBUG   __main__.main INPUTS:
+just run src/model/train.py
+# 2038-01-19 03:14:08,000 INFO    train.py.main START
+# 2038-01-19 03:14:08,001 DEBUG   train.py.main INPUTS:
 # 2038-01-19 03:14:08,002 INFO    src.model.io.save_model START
 # 2038-01-19 03:14:08,003 DEBUG   src.model.io.save_model INPUTS: model=42, model_name='model'
 # 2038-01-19 03:14:08,004 INFO    src.model.io.get_path START
@@ -353,8 +351,8 @@ $ uv run src/model/train.py
 # 2038-01-19 03:14:08,007 DEBUG   src.model.io.get_path OUTPUT: 'models/model.cldpkl'
 # 2038-01-19 03:14:08,008 INFO    src.model.io.save_model END
 # 2038-01-19 03:14:08,009 DEBUG   src.model.io.save_model OUTPUT: None
-# 2038-01-19 03:14:08,010 INFO    __main__.main END
-# 2038-01-19 03:14:08,011 DEBUG   __main__.main OUTPUT: None
+# 2038-01-19 03:14:08,010 INFO    train.py.main END
+# 2038-01-19 03:14:08,011 DEBUG   train.py.main OUTPUT: None
 ```
 Forcing yourself to only log via decorators can have some positive side effects:
 If you feel like you would like to add some logging within a function, this can be an indicator that the code block in question is a candidate to be refactored into a separate function.
@@ -368,24 +366,27 @@ All of these parameters should be handed to the code via environment variables.
 
 > A litmus test for whether an app has all config correctly factored out of the code is whether the codebase could be made open source at any moment, without compromising any credentials.[^6]
 
-That is why this template comes with [`python-dotenv`](https://pypi.org/project/python-dotenv/) pre-installed.
-Simply create a file named `.env` in the project root folder and enter your configration parameters:
+To store your secrets create a file named `.env` in the project root folder and enter your configration parameters:
 ```ini
 DATABASE_URL=postgres://localhost:1337/dbname
 DATBASE_USER=myusername
 DATABASE_PASSWORD=topsneaky
 ```
+Scripts run via [`just`](https://github.com/casey/just) automatically load these entries as environment variables.
+```bash
+just run src/script.py
+```
 In your code you can access these screts like this:
 ```python
+# src/script.py
 import os
-from dotenv import load_dotenv
-
-load_dotenv()
 
 database_url = os.getenv("DATABASE_URL")
 ```
 Thanks to the `.gitignore`, the `.env` file will not get committed into the git repository.
 
+Alternatively you can also use [`python-dotenv`](https://pypi.org/project/python-dotenv/) to load secrets from `.env` files.
+
 ## First steps
 
 ### Installing a package

reproML/just.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+uv run just $@

reproML/justfile

@@ -0,0 +1,23 @@
+set dotenv-load
+
+# shows this list
+default:
+  uv run just --list
+
+# runs a python script's main method
+run SCRIPT *ARGS:
+  uv run typer {{SCRIPT}} run {{ARGS}}
+
+# installs all dependecies and pre-commit hooks
+install:
+  uv sync --all-groups --all-extras
+  uv run pre-commit install --hook-type pre-push --hook-type post-checkout --hook-type pre-commit
+
+# runs quality checks on all files
+check:
+  uv run pre-commit run --all-files
+
+# starts the documentation server
+docs:
+  -uv run interrogate
+  -uv run mkdocs serve