prepare-assignment 0.2.1__tar.gz → 0.4.0__tar.gz

prepare_assignment-0.4.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,18 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: '[Bug] '
+labels: ["bug"]
+assignees: ''
+---
+
+## Describe the bug
+A clear and concise description of what the bug is.
+
+## Expected behavior
+A clear and concise description of what you expected to happen.
+
+## To Reproduce
+Steps to reproduce the behavior:
+
+1. 

prepare_assignment-0.4.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

prepare_assignment-0.4.0/.github/dependabot.yml

@@ -0,0 +1,25 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    # PR titles must follow Conventional Commits (checked by pr-title.yml)
+    commit-message:
+      prefix: "build"
+      include: "scope"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "ci"
+      include: "scope"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

prepare_assignment-0.4.0/.github/workflows/pr-title.yml

@@ -0,0 +1,39 @@
+name: PR title
+
+# With squash merging the PR title becomes the commit subject on main, which is
+# what semantic-release parses to pick the next version. An unparseable title
+# is therefore a release that silently does not happen.
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, edited, synchronize, reopened]
+
+concurrency:
+  group: pr-title-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  pull-requests: read
+
+jobs:
+  lint:
+    name: conventional title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # The types already in use on main, plus revert.
+          types: |
+            feat
+            fix
+            docs
+            refactor
+            test
+            ci
+            style
+            chore
+            perf
+            build
+            revert

prepare_assignment-0.4.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,45 @@
+name: PyPI publish
+
+# Reusable build and publish. Two callers pass a version in:
+#   - release.yml           on a human-pushed v* tag
+#   - semantic-release.yml  after semantic-release cuts a new version
+#
+# It lives here rather than in either caller because a tag pushed with
+# GITHUB_TOKEN does not trigger workflows, so semantic-release cannot rely on
+# release.yml's tag trigger to publish the version it just cut.
+on:
+  workflow_call:
+    inputs:
+      version:
+        description: Version to build and publish, without the leading v (e.g. 1.2.3).
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: build & publish
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.1.0
+        with:
+          python-version: "3.12"
+
+      # The version is not committed back to main, so the version in
+      # pyproject.toml is stale. Set the released version just for this build.
+      - name: Set version
+        run: uv version "${{ inputs.version }}" --frozen
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}

prepare_assignment-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,33 @@
+name: Release
+
+# Fires only on tags pushed by a human: a manual tag cut as an escape hatch.
+# Routine releases come from semantic-release.yml, whose GITHUB_TOKEN-pushed
+# tags deliberately do not trigger this workflow — that is what keeps a
+# release from being published twice.
+on:
+  push:
+    tags: ["v*"]
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  version:
+    name: version from tag
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+  publish:
+    needs: version
+    uses: ./.github/workflows/pypi-publish.yml
+    with:
+      version: ${{ needs.version.outputs.version }}
+    secrets: inherit

prepare_assignment-0.4.0/.github/workflows/semantic-release.yml

@@ -0,0 +1,57 @@
+name: Semantic release
+
+on:
+  push:
+    branches: [main]
+
+# Never cancel a release mid-flight: a half-run that has tagged but not yet
+# published would need cleaning up by hand.
+concurrency:
+  group: semantic-release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: version
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the tag and the GitHub release
+      issues: write # comment "released in vX.Y.Z" on issues
+      pull-requests: write # and on the PRs that fed the release
+    outputs:
+      published: ${{ steps.semantic.outputs.new_release_published }}
+      version: ${{ steps.semantic.outputs.new_release_version }}
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # semantic-release walks back to the previous tag to decide the bump,
+          # so a shallow clone makes it compute the wrong version.
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+
+      # Pinned to an exact version: this action publishes no floating major
+      # tags, so @v6 would not resolve. All three plugins in .releaserc.json
+      # ship with the semantic-release core it bundles.
+      - name: Semantic release
+        id: semantic
+        uses: cycjimmy/semantic-release-action@v6.0.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # The tag above was pushed with GITHUB_TOKEN, so it will not trigger
+  # release.yml. Publish to PyPI here instead.
+  publish:
+    needs: release
+    if: needs.release.outputs.published == 'true'
+    uses: ./.github/workflows/pypi-publish.yml
+    with:
+      version: ${{ needs.release.outputs.version }}
+    secrets: inherit

prepare_assignment-0.4.0/.github/workflows/test.yml

@@ -0,0 +1,63 @@
+name: Test
+
+defaults:
+  run:
+    shell: bash
+
+# Only on pull requests: main only changes through squash-merged PRs, which
+# have already passed these checks.
+on:
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        os: ["ubuntu-latest", "windows-latest", "macos-latest"]
+    runs-on: ${{ matrix.os }}
+    permissions:
+      contents: read
+      checks: write
+    steps:
+    - uses: actions/checkout@v7
+    - name: Install uv and Python ${{ matrix.python-version }}
+      uses: astral-sh/setup-uv@v10.1.0
+      with:
+        python-version: ${{ matrix.python-version }}
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
+        cache-suffix: py${{ matrix.python-version }}
+    - name: Install dependencies
+      run: uv sync --locked --group test
+    - name: Run tests
+      env:
+        PREPARE_TEST_GIT_MODE: https
+      run: uv run pytest --cov --cov-report=xml --junitxml=tests.xml
+    - name: Test Report
+      uses: mikepenz/action-junit-report@v6
+      if: success() || failure()
+      with:
+        check_name: Test Results (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+        report_paths: tests.xml
+
+  typecheck:
+    strategy:
+      matrix:
+        python-version: [ "3.12" ]
+    runs-on: "ubuntu-latest"
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv and Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@v10.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+          cache-suffix: typecheck
+      - name: Install dependencies
+        run: uv sync --locked --group test
+      - name: Type checker
+        run: uv run mypy prepare_assignment

prepare_assignment-0.4.0/.gitignore

@@ -0,0 +1,165 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+exampleproject/
+tests.xml
+out.txt
+out/
+.vscode

prepare_assignment-0.4.0/.releaserc.json

@@ -0,0 +1,9 @@
+{
+  "branches": ["main"],
+  "tagFormat": "v${version}",
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/github"
+  ]
+}

prepare_assignment-0.4.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.5
+Name: prepare-assignment
+Version: 0.4.0
+Summary: Prepare assignment
+Author-email: Bonajo <m.bonajo@fontys.nl>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: dacite>=1.9.2
+Requires-Dist: gitpython>=3.1.59
+Requires-Dist: jsonschema>=4.21.1
+Requires-Dist: multipledispatch>=1.0.0
+Requires-Dist: packaging>=24.0
+Requires-Dist: prepare-toolbox==0.4.0
+Requires-Dist: ruamel-yaml>=0.18.5
+Requires-Dist: simpleeval>=1.0.0
+Requires-Dist: treelib>=1.7.0
+Requires-Dist: typer==0.27.2
+Requires-Dist: virtualenv>=20.25.0
+Description-Content-Type: text/markdown
+
+# Prepare assignment
+
+Prepare assignment is a GitHub Actions inspired helper tool to prepare assignments at Fontys Venlo. The goal is to define jobs inside the `prepare.yml` that indicate how to convert a solution project into a student project.
+
+## Dependencies
+
+- Git
+- Python >=3.11
+
+## Installation
+
+Prepare-assignment is available from [PyPI](https://pypi.org/).
+
+
+```bash
+# To install:
+python3 -m pip install prepare-assignment
+
+# To upgrade
+python3 -m pip install --upgrade prepare-assignment
+```
+
+## Executing prepare-assignment
+
+To execute a `prepare.yml` simply run `prepare run` from the same directory.
+
+### Command line interface
+
+Use `prepare --help` to which commands and flags are available.
+
+## Example `prepare.yml`
+
+First we need to have tasks available that can be executed. Take for example a look at the [remove](https://github.com/prepare-assignment/remove) task.
+
+The tests use a [testproject](https://github.com/prepare-assignment/core/tree/tests/testproject), which contains an example of a `prepare.yml`, see below for convenience.
+
+```yaml
+name: Test project
+jobs:
+  prepare:
+    - name: remove out
+      uses: remove
+      with:
+        input:
+          - "out"
+          - "out.txt"
+        force: true
+        recursive: true
+    - name: codestripper
+      id: codestripper
+      uses: codestripper
+      with:
+        include:
+          - "**/*.java"
+          - "pom.xml"
+        working-directory: "solution"
+        verbosity: 5
+    - name: Test a run command with substitution
+      run: echo '${{ tasks.codestripper.outputs.stripped-files }}' > out.txt
+```
+
+For people familiar with GitHub Actions this should look very familiar. We have jobs that indicate what should happen to prepare an assignment. The tasks are defined in their own repositories, if the `uses` tag doesn't have a username/organization, it will default to `prepare-assignment`. So for example the `remove` task uses the following repository: [prepare-assignment/remove](https://github.com/prepare-assignment/remove)
+
+## Step reference
+
+Every step has a `name` and either `uses` (a task) or `run` (a shell command).
+
+| Property            | Applies to     | Description                                                                                                |
+|---------------------|----------------|------------------------------------------------------------------------------------------------------------|
+| `name`              | all            | Name of the step (required)                                                                                |
+| `id`                | all            | Identifier used to reference the outputs of the step: `${{ tasks.<id>.outputs.<name> }}`                   |
+| `if`                | all            | Only run the step if the expression is true, see [Conditions](#conditions)                                 |
+| `uses`              | task           | The task to execute, e.g. `remove`, `remove@v1`, `my-org/my-task@v1.2.0`                                   |
+| `with`              | task           | The inputs of the task                                                                                     |
+| `run`               | run            | The command (script) to execute                                                                            |
+| `shell`             | run            | `bash` (default), `sh`, `pwsh`, `powershell`, `cmd` or `python`                                            |
+| `working-directory` | all            | Directory (relative to the `prepare.yml`) in which the step is executed                                    |
+| `env`               | all            | Environment variables for this step only, values can contain expressions                                   |
+| `continue-on-error` | all            | If `true`, a failure of this step doesn't fail the job                                                     |
+
+The default shell can be changed in the [config file](#config-file). Using `shell: python` is the most portable
+option, as Python is always available.
+
+Like GitHub Actions, the script is written to a temporary file and executed as:
+
+| Shell        | Command                                                         | Behaviour                                                        |
+|--------------|-----------------------------------------------------------------|------------------------------------------------------------------|
+| `bash`       | `bash --noprofile --norc -eo pipefail <file>`                   | Stops at the first failing command (also inside a pipe)          |
+| `sh`         | `sh -e <file>`                                                  | Stops at the first failing command                               |
+| `pwsh`       | `pwsh -NoProfile -NonInteractive -Command ". '<file>'"`         | Stops at the first error, fails if the last program failed       |
+| `powershell` | `powershell -NoProfile -NonInteractive -Command ". '<file>'"`   | Same as `pwsh` (Windows PowerShell 5.1)                          |
+| `cmd`        | `cmd /D /E:ON /V:OFF /S /C "CALL "<file>""`                     | Doesn't stop on errors, the exit code of the last command counts |
+| `python`     | `python <file>`                                                 | The Python interpreter that runs prepare                         |
+
+```yaml
+- name: Create checksum
+  shell: python
+  working-directory: out/assignment
+  run: |
+    import hashlib
+    digest = hashlib.sha256(open("pom.xml", "rb").read()).hexdigest()
+    open("pom.xml.sha256", "w").write(f"{digest}  pom.xml\n")
+```
+
+### Expressions
+
+Values can contain expressions: `${{ <expression> }}`. The following contexts are available:
+
+- `inputs.<name>`: the inputs of a composite task
+- `env.<NAME>`: environment variables (an unset variable is empty)
+- `tasks.<id>.outputs.<name>`: the outputs of a previous step
+
+Referencing something that doesn't exist (e.g. a typo like `inputs.nmae`) fails the step, instead of silently
+evaluating to an empty string. The operators `==`, `!=`, `<`, `>`, `&&`, `||` and `!` and the functions
+`contains`, `startsWith` and `endsWith` are supported.
+
+### Conditions
+
+Just like GitHub Actions, a step is skipped when a previous step failed, unless its `if` uses one of the status
+functions `success()`, `failure()` or `always()`. So `if: inputs.clean` behaves as `success() && inputs.clean`.
+
+```yaml
+- name: Clean up (also when something failed)
+  if: always()
+  uses: remove
+  with:
+    input: ["out"]
+    force: true
+    recursive: true
+```
+
+## Checking for updates
+
+`prepare check` shows which of the tasks used in the `prepare.yml` have newer versions (use `--all` to check all
+installed tasks). Tasks that use a moving version (`latest`, `main` or a prefix like `v1`) can be updated with
+`prepare task update <task>`.
+
+## Config file
+
+It is possible to specify global options in a config file. The location of the config file can be found by running `prepare` without any commands.
+
+The following settings are available:
+
+```yml
+core:
+  git-mode: "ssh|https"
+  verbose: int
+  debug: int
+  shell: "bash|sh|pwsh|powershell|cmd|python" # default shell for run steps (default: bash)
+```
+
+## Tasks
+
+There are three different kind of tasks available:
+
+- Run tasks: these execute a shell command (see `shell` below)
+- Python tasks: these execute a python script
+- Composite tasks: these combine multiple tasks into one
+
+### Custom tasks
+
+It is possible to create custom (python/composite) tasks.
+
+1. Create a repository
+2. Define the properties of the task in `task.yml`, these include
+    - id*: unique identifier
+    - name*: name of the task
+    - description*: short description
+    - runs*: whether it is a python or composite task
+    - inputs: the inputs for the task
+    - outputs: the outputs that get set by the task. For composite tasks an output gets its value from an
+      expression: `value: ${{ tasks.<id>.outputs.<name> }}`
+3. Validate that the task definition is correct against the [json schema](https://github.com/prepare-assignment/core/blob/main/prepare_assignment/schemas/task.schema.json)
+4. If python task, create a script that implements desired functionality
+
+## Releases
+
+Releases are automated with [semantic-release](https://semantic-release.gitbook.io/). Pull requests are squash merged, so the PR title becomes the commit on `main` and must follow [Conventional Commits](https://www.conventionalcommits.org/) (checked on every PR):
+
+| PR title | Release |
+|----------|---------|
+| `fix: ...` | patch (1.2.3 → 1.2.4) |
+| `feat: ...` | minor (1.2.3 → 1.3.0) |
+| `feat!: ...` or a `BREAKING CHANGE:` footer | major (1.2.3 → 2.0.0) |
+| `docs:`, `chore:`, `ci:`, `build:`, `refactor:`, `test:`, `style:`, `perf:` | no release |
+
+On every merge to `main` the next version is determined, tagged (`vX.Y.Z`), a GitHub release is created and the package is published to PyPI. The version is set during the build and is not committed, so the version in `pyproject.toml` is not the released version.