ResultWizard project

.github/actions/changed_files/action.yml

@@ -0,0 +1,42 @@
+# Why is this file in a subdirectory? Because GitHub Actions requires it to be :(
+# see: https://github.com/orgs/community/discussions/26245#discussioncomment-5962450
+name: "Get changed files"
+description: "Checks out the code and returns the filenames of files that have changed in the pull request"
+
+inputs:
+  file-extensions:
+    # for example: "\.py$" or something like "\.py$|\.py.myfile$"
+    description: "Regex expressions for grep to filter for specific files"
+    required: true
+
+outputs:
+  changed-files:
+    description: "A space-separated list of the files that have changed in the pull request"
+    value: ${{ steps.get-changed-files.outputs.files }}
+
+runs:
+  using: "composite"
+  steps:
+    # This has to be done in the main workflow, not in the action, because
+    # otherwise this reusable action is not available in the workflow.
+    # - name: "Checkout code (on a PR branch)"
+    #   uses: actions/checkout@v4
+    #   with:
+    #     fetch-depth: 2 # to also fetch parent of PR
+
+    # Adapted from this great comment [1]. Git diff adapted from [2].
+    # "|| test $? = 1;" is used to ignore the exit code of grep when no files
+    # are found matching the pattern. For the "three dots" ... syntax, see [3].
+    #
+    # Resources:
+    # number [1] being most important
+    # [1] https://github.com/actions/checkout/issues/520#issuecomment-1167205721
+    # [2] https://robertfaldo.medium.com/commands-to-run-rubocop-and-specs-you-changed-in-your-branch-e6d2f2e4110b
+    # [3] https://community.atlassian.com/t5/Bitbucket-questions/Git-diff-show-different-files-than-PR-Pull-Request/qaq-p/2331786
+    - name: Get changed files
+      shell: bash
+      id: get-changed-files
+      run: |
+        files_pretty=$(git diff --name-only --diff-filter=ACMR -r HEAD^1...HEAD | egrep '${{inputs.file-extensions}}' || test $? = 1;)
+        printf "🎴 Changed files: \n$files_pretty"
+        echo "files=$(echo ${files_pretty} | xargs)" >> $GITHUB_OUTPUT

.github/workflows/linter.yml

@@ -0,0 +1,50 @@
+name: Linting
+
+# for "synchronize", see [1]
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
+
+jobs:
+  pylint:
+      name: Pylint
+      runs-on: ubuntu-latest
+      steps:
+        - name: Checkout code
+          uses: actions/checkout@v4
+          with:
+            fetch-depth: 2 # to also fetch parent of PR (used to get changed files)
+
+        - name: Get changed files
+          id: py-changed
+          uses: ./.github/actions/changed_files/
+          with:
+            file-extensions: \.py$
+
+        - name: Setup Python
+          if: ${{ steps.py-changed.outputs.changed-files != ''}}
+          uses: actions/setup-python@v5
+          with:
+            python-version: '3.11'
+            cache: 'pipenv'
+
+        # see Caching [2]
+        - name: Install pipenv
+          if: ${{ steps.py-changed.outputs.changed-files != ''}}
+          run: pip install pipenv
+
+        - name: Install dependencies
+          if: ${{ steps.py-changed.outputs.changed-files != ''}}
+          run: pipenv install --dev
+
+        # For GitHub output format, see [3]
+        - name: Run Pylint
+          if: ${{ steps.py-changed.outputs.changed-files != ''}}
+          run: |
+            echo "🚨 Running Pylint version: $(pipenv run python3 -m pylint --version)"
+            pipenv run python3 -m pylint ${{ steps.py-changed.outputs.changed-files }}
+
+
+# [1] https://github.com/orgs/community/discussions/26366
+# [2] https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md#caching-packages
+# [3] https://github.com/pylint-dev/pylint/issues/9443

.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  releasepypi:
+    # see https://docs.pypi.org/trusted-publishers/using-a-publisher/
+    # and https://packaging.python.org/en/latest/tutorials/packaging-projects/#uploading-the-distribution-archives
+    name: Release to PyPI
+    runs-on: "ubuntu-latest"
+    environment: release
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+          cache: 'pipenv'
+
+      - name: Run tests (one last time before release)
+        run: |
+          pip install pipenv
+          pipenv install --dev
+          pipenv run pip3 install --editable .
+          pipenv run pytest tests/
+
+      - name: Install build tooling
+        run: python3 -m pip install --upgrade build
+
+      - name: Build distributions
+        run: python3 -m build
+
+      - name: Upload to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/tests.yml

@@ -0,0 +1,40 @@
+name: Testing
+
+on:
+  push:
+    branches:
+      - main
+
+  # for "synchronize", see [1]
+  pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
+
+jobs:
+    pytest:
+        name: Pytest
+        runs-on: ubuntu-latest
+        steps:
+          - name: Checkout code
+            uses: actions/checkout@v4
+
+          - name: Setup Python
+            uses: actions/setup-python@v5
+            with:
+              python-version: 3.11
+              cache: 'pipenv'
+
+          - name: Install pipenv
+            run: pip install pipenv
+
+          - name: Install dependencies (including dev dependencies)
+            run: pipenv install --dev
+
+          - name: Install ResultWizard itself (as editable)
+            run: pipenv run pip3 install --editable .
+
+          - name: Run Pytest
+            run: pipenv run pytest tests/
+
+
+
+# [1] https://github.com/orgs/community/discussions/26366

.gitignore

@@ -1,5 +1,5 @@
-.vscode/
 /test/
 */__pycache__
 __pycache__
-*.tex
+*.tex
+*.egg-info

.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+    "recommendations": [
+        "streetsidesoftware.code-spell-checker",
+        "ms-python.pylint",
+        "ms-python.black-formatter",
+        "littlefoxteam.vscode-python-test-adapter",
+        "hbenl.vscode-test-explorer"
+    ]
+}

.vscode/launch.json

@@ -0,0 +1,19 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug test (only use for tests)",
+            "type": "python",
+            "request": "attach",
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "stopOnEntry": false,
+            "purpose": [
+                "debug-test"
+            ]
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,87 @@
+{
+    //////////////////////////////////////
+    // Python (linting & formatting)
+    //////////////////////////////////////
+    "[python]": {
+        "editor.defaultFormatter": "ms-python.black-formatter",
+        "editor.formatOnSave": true
+    },
+    "pylint.importStrategy": "fromEnvironment",
+    "python.analysis.typeCheckingMode": "basic",
+    "python.languageServer": "Pylance",
+    "python.analysis.completeFunctionParens": true,
+    "python.analysis.diagnosticSeverityOverrides": {
+        "reportGeneralTypeIssues": "warning",
+        "reportUndefinedVariable": "warning",
+        "reportOptionalMemberAccess": "warning"
+    },
+    // Python Tests
+    "pythonTestExplorer.testFramework": "pytest",
+    "testExplorer.codeLens": true,
+    "testExplorer.errorDecorationHover": true,
+    "python.testing.pytestArgs": [
+        "."
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    //////////////////////////////////////
+    // Files
+    //////////////////////////////////////
+    "files.exclude": {
+        "**/__pycache__/": true,
+        "**/*.egg-info/": true,
+        ".pytest_cache/": true
+    },
+    //////////////////////////////////////
+    // Editor
+    //////////////////////////////////////
+    "editor.tabSize": 4,
+    "editor.insertSpaces": true,
+    "editor.detectIndentation": false,
+    "editor.wordWrap": "wordWrapColumn",
+    "editor.wordWrapColumn": 100, // toggle via Alt + Z shortcut
+    "editor.mouseWheelZoom": true,
+    "editor.rulers": [
+        {
+            "column": 80, // soft limit
+            "color": "#e5e5e5"
+        },
+        {
+            "column": 100, // hard limit
+            "color": "#c9c9c9"
+        }
+    ],
+    //////////////////////////////////////
+    // Git
+    //////////////////////////////////////
+    "git.inputValidation": true,
+    "git.inputValidationSubjectLength": 50,
+    "git.inputValidationLength": 72,
+    //////////////////////////////////////
+    // Spell Checker
+    //////////////////////////////////////
+    "cSpell.words": [
+        "github",
+        "ifthen",
+        "ifthenelse",
+        "justfile",
+        "latexer",
+        "newcommand",
+        "normalsize",
+        "pipenv",
+        "pydantic",
+        "pylint",
+        "pytest",
+        "resultwizard",
+        "scriptsize",
+        "scriptstyle",
+        "sigfigs",
+        "siunitx",
+        "Stringifier",
+        "textbf",
+        "texttt",
+        "TLDR",
+        "uncert",
+        "usepackage"
+    ]
+}

CHANGELOG.md

@@ -0,0 +1,3 @@
+# Changelog
+
+👀 Nothing here yet

DEVELOPMENT.md

@@ -0,0 +1,68 @@
+# Development Guideline/Conventions/Installation
+
+Just a dump for right now. In construction... Maybe a wiki would also be a good place for this.
+
+
+## Checklist
+Getting ready:
+- [ ] GPG key setup to sign commits
+- [ ] Recommended VSCode extensions installed (especially the formatter. It should automatically format on every save!)
+- [ ] on branch `value-wizard` with latest commit pulled
+- [ ] Work through the `Setup` section below (especially to install the necessary dependencies)
+- [ ] Read the [`README.md`](https://github.com/paul019/ResultWizard/tree/value-wizard/src#code-structure) in the `src` folder (to get to know the code structure) & see our [feature list](https://github.com/paul019/ResultWizard/issues/16)
+
+Verify that everything worked:
+- [ ] try to run the tests, see the instructions in [`tests/playground.py`](./tests/playground.py)
+
+Then start working on the code:
+- [ ] search for "TODO"s in the code, they will guide you to the next steps
+- [ ] document and append to `tests/playground.py` what we expect as user when using this library (we will use this as a reference to test the library later on)
+- [ ] try to add doc-strings early on (in relevant places), so that I know what you are doing (and you know what I'm doing :))
+- [ ] discuss when you want to restructure `domain` objects (e.g. `_Value`), e.g. if you are annoyed of having to deal with strings instead of floats (but I think with strings we are more flexible)
+
+
+## Setup
+
+- Install the recommended VSCode extensions. This includes `pylint` (Python linting) and `black` (Python formatting). VSCode is setup via the `settings.json` to format on save.
+
+> [!Tip]
+> I've specified recommended extensions, you can install them in VSCode by using [the "recommended" filter](https://code.visualstudio.com/docs/editor/extension-marketplace#_extensions-view-filter-and-commands).
+
+- Install [pipenv](https://pipenv.pypa.io/en/latest/installation.html). I added this to my `.bashrc`:
+  ```bash
+  alias python3=python3.11
+  export PATH="$PATH:~/.local/bin"
+  ```
+- Install the dependencies: `pipenv install`
+- Type in `pipenv` to see available commands, e.g. `pipenv shell` etc.
+
+
+## TODO
+- Setup `.editorconfig` for non-VSCode users. At least provide very basic setup like max line length etc.
+- A [`justfile`](https://github.com/casey/just) would also be beneficial.
+
+
+
+## Testing ❌✅
+
+As always, make sure you are in the `pipenv shell`.
+
+Make sure you have all (dev) dependencies installed:
+
+```
+pipenv install -d
+```
+
+Then you can run the tests via the command line:
+
+```
+pytest
+```
+
+But with VSCode, you get direct integration into the **Test Explorer UI**. You will have to install the recommended extensions first. Then switch to the Testing tab and you will find the tests there. You can run them from there, jump to the file where they are defined and even start debugging them. You can also do the same via the code lens (it shows a little menu "Run | Debug | ..." over every test method) in the test files themselves. Try to set a breakpoint and debug it by clicking "Debug" in the code lens. While debugging, go the debug panel and see some variables there or enter one in the watch tab. Try to modify a test such that it fails and get to know where you see the error.
+
+Also try adding `import pytest` as first line of a test file. Does it give you a warning? If so, you have selected the wrong VSCode Python interpreter. Choose the one provided by the pipenv virtual environment where all dependencies are installed.
+
+Note that tests are also run on every commit via a GitHub action.
+
+In order to learn how to write the tests with pytest, start with the [`Get Started` guide](https://docs.pytest.org/en/8.0.x/getting-started.html#create-your-first-test). Probably also relevant: ["How to use fixtures"](https://docs.pytest.org/en/8.0.x/how-to/fixtures.html). There are lots of [How-to guides](https://docs.pytest.org/en/8.0.x/how-to/index.html) available.