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.
# 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 see 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 task.
The tests use a testproject, which contains an example of a prepare.yml, see below for convenience.
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
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 |
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. 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 |
- 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 taskenv.<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.
- 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:
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
shellbelow) - 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.
- Create a repository
- 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> }}
- Validate that the task definition is correct against the json schema
- If python task, create a script that implements desired functionality
Releases
Releases are automated with semantic-release. Pull requests are squash merged, so the PR title becomes the commit on main and must follow Conventional Commits (checked on every PR):
| PR title | Release |
|---|---|
fix: ..., perf: ... |
patch (1.2.3 → 1.2.4) |
feat: ... |
minor (1.2.3 → 1.3.0) |
! after the type (e.g. feat!: ..., refactor!: ...) or a BREAKING CHANGE: footer |
major (1.2.3 → 2.0.0) |
docs:, chore:, ci:, build:, refactor:, test:, style:, revert: |
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.
Metadata
Release files for prepare-assignment 0.4.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| prepare_assignment-0.4.4.tar.gz | 121.7 kB | Without provenance | Details for prepare_assignment-0.4.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| prepare_assignment-0.4.4-py3-none-any.whl | Python 3 | none | any | Details for prepare_assignment-0.4.4-py3-none-any.whl |
Total release size: 169.7 kB
Release files / prepare_assignment-0.4.4.tar.gz
| Download URL | prepare_assignment-0.4.4.tar.gz |
|---|---|
| Size | 121.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1c0a2d1cc7d153458eb055a5e58b264603a203d64c9e7cb9ad6d25c057d8b982
|
|
BLAKE2b-256 checksum How to use checksums |
d5857a071f5022680c861083839b756df188f2a6cee94f6ae0ef6066cf0bc8a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / prepare_assignment-0.4.4-py3-none-any.whl
| Download URL | prepare_assignment-0.4.4-py3-none-any.whl |
|---|---|
| Size | 48.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cbfac4e56d13e6d3ad1f52ac19695ece28c471743b1ff904d696348408746167
|
|
BLAKE2b-256 checksum How to use checksums |
622cdfdf9184ea772d37de2709d3e3e51ed586f27cc2a2d165fc37d342231860
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.18 {"installer":{"name":"uv","version":"0.12.18","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for prepare-assignment 0.4.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.