readme and some minor print statement fixes

Author: memalhot

README.md

@@ -1,69 +1,206 @@
-# python-batchtools
+ python-batchtools
 
-## Set up your development environment
+## Overview
 
-### Install tools
+`python-batchtools` is a CLI for students and researchers to
+submit **GPU batch jobs** through **Kueue-managed GPU queues** on an
+OpenShift cluster. It provides an inexpensive and accessible way to use
+GPU hardware without reserving dedicated GPU nodes.
 
-1. Start by installing `uv`. Depending on your distribution, this may be as simple as:
+Users submit GPU jobs with a single command:
 
-    ```sh
-    sudo dnf -y install uv
-    ```
+``` sh
+batchtools br "./cuda_program"
+```
+
+The CLI automatically:
+- Creates the batch job<br>
+- Submits it to the appropriate Kueue-managed LocalQueue<br>
+- Tracks job status<br>
+- Streams logs on completion <br>
+
+
+# For Users
 
-    If you would like to run the latest version, you can install the command using `pipx`. First, install `pipx`:
+## Installation
 
-    ```
-    sudo dnf -y install pipx
-    ```
+### Option 1: Use the provided container image (recommended)
 
-    And then use `pipx` to install `uv`:
+### Option 2: Install from source
+
+``` sh
+git clone https://github.com/memalhot/python-batchtools.git
+cd python-batchtools
+pip install -e .
+```
 
-    ```
-    pipx install uv
-    ```
 
-2. Next, install `pre-commit`. As with `uv`, you can install this using your system package manager:
+## Prerequisites
 
-    ```
-    sudo dnf -y install pre-commit
-    ```
+1.  A Kueue-enabled OpenShift cluster, with local-queues named: v100-localqueue, a100-localqueue, h100-localqueue, dummy-localqueue<br>
+2.  An OpenShift account<br>
+3.  The Python OpenShift client:
+
+``` sh
+pip install openshift-client
+```
 
-    Or you can install a possibly more recent version using `pipx`:
+# Usage Examples
 
-    ```
-    pipx install pre-commit
-    ```
+For any command you can run:
+`batchtools <command> -h` or `batchtools <command> --help`
 
+## **1. Submit a Batch Job --- `br`**
+The br command is how to submit batchjobs. It submits code intended to run on GPUs to the Kueue, where it is queued, then run, produces logs stored in the `RUNDIR`, and then deletes the job for resource conservation.
 
-### Activate pre-commit
+Here's how to use thed br command:
 
-Activate `pre-commit` for your working copy of this repository by running:
+First write a CUDA program and compile it :D
+Then to submit your CUDA program to the GPU node:
 
+``` sh
+batchtools br "./cuda-code"
 ```
-pre-commit install
+
+Submit a program with arguments:
+
+``` sh
+batchtools br './simulate --steps 1000'
+```
+
+Specify GPU type:
+
+``` sh
+batchtools br --gpu v100 "./train_model"
+```
+
+Run without waiting for logs (for longer runs, similar to a more traditional batch system):
+
+``` sh
+batchtools br --no-wait "./cuda_program"
 ```
+***WARNING***
+If you run br with the --no-wait flag, it will not be cleaned up for you. You must delete it on your own by running `batchtools bd <job-name>` or `oc delete job <job-name>`
+But don't worry, running with --no-wait will give you a reminder to delete your jobs!
 
-This will configure `.git/hooks/pre-commit` to run the `pre-commit` tool every time you make a commit. Running these tests locally ensures that your code is clean and that tests are passing before you share your code with others. To manually run all the checks:
+And if you need help or want to see more flas:
 
+``` sh
+batchtools br --h
 ```
-pre-commit run --all-files
+
+
+## **2. List Jobs --- `bj`**
+
+List all jobs:
+
+``` sh
+batchtools bj
 ```
 
 
-### Install dependencies
+## **3. Delete Jobs --- `bd`**
 
-To install the project dependencies, run:
+Delete all jobs:
 
+``` sh
+batchtools bd
 ```
-uv sync --all-extras
+
+To delete specific jobs:
+
+``` sh
+batchtools bd job-a job-b
 ```
 
-### Run tests
 
-To run just the unit tests:
+## **4. List active GPU pods per node --- `bps`**
+
+``` sh
+batchtools bps
+```
+
+Output will be empty if all nodes are free.
+
+If some nodes are busy:
+```
+wrk-4: BUSY 3 project-1/project-stuff testing/other-stuff test/fraud-detectiob
+```
+
+To always ensure output, you can run:
 
+``` sh
+batchtools --verbose bps
 ```
+To get output like:
+```
+ctl-0: FREE
+ctl-1: FREE
+ctl-2: FREE
+wrk-0: FREE
+wrk-1: FREE
+wrk-3: FREE
+wrk-4: BUSY 3 project-1/project-stuff testing/other-stuff test/fraud-detection
+wrk-5: FREE
+wrk-6: FREE
+wrk-7: FREE
+
+```
+
+## **5. Show pod logs --- `bl`**
+
+``` sh
+batchtools bl
+```
+
+For a specific pod:
+``` sh
+batchtools bl pod-name
+```
+
+
+## **6. Show pod logs --- `bq`**
+
+``` sh
+batchtools bq
+```
+
+Output will look like:
+``` sh
+a100-clusterqueue       admitted: 0     pending: 0      reserved: 0     GPUs: 0 BestEffortFIFO
+dummy-clusterqueue      admitted: 0     pending: 0      reserved: 0     GPUs: 0 BestEffortFIFO
+h100-clusterqueue       admitted: 0     pending: 0      reserved: 0     GPUs: 0 BestEffortFIFO
+v100-clusterqueue       admitted: 0     pending: 0      reserved: 0     GPUs: 3 BestEffortFIFO
+```
+
+# For Contributors
+
+## Tools
+
+Install uv:
+
+``` sh
+pipx install uv
+```
+
+Install pre-commit:
+
+``` sh
+pipx install pre-commit
+```
+
+Activate hooks:
+
+``` sh
+pre-commit install
+```
+
+## Running Tests
+
+``` sh
 uv run pytest
 ```
 
-This will generate a test coverage report in `htmlcov/index.html`.
+Coverage report is generated at:
+
+    htmlcov/index.html

batchtools/br.py

@@ -228,11 +228,11 @@ def run(args: argparse.Namespace):
             oc_delete("job", job_name)
         else:
             print(
-                f"User specified not to wait, or not to delete, so {job_name} must be deleted by user."
+                f"User specified not to wait, or not to delete, so {job_name} must be deleted by user.\n"
+                f"You can do this by running:\n"
+                f"  bd {job_name} OR\n"
+                f"  oc delete job {job_name}"
             )
-            print("You can do this by running:")
-            print(f"bd {job_name} OR ")
-            print(f"oc delete job {job_name}")
 
 
 def get_pod_status(pod_name: str | None = None) -> str:

tests/test_bj.py

@@ -70,7 +70,7 @@ def test_lists_all_jobs_and_count(capsys):
         assert sel.calls.count("jobs") == 1
 
 
-def test_lists_jobs_ignoring_workloads_or_kueue_details(capsys):
+def test_lists_jobs(capsys):
     """
     Regression test: ensure that ListJobsCommand behavior is simple:
     it just lists whatever oc.selector("jobs").objects() returns,