Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
80 changes: 11 additions & 69 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -11,80 +11,22 @@ jobs:
qa:
runs-on: ubuntu-latest
timeout-minutes: 15

steps:
- name: Check out repository
uses: actions/checkout@v4

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.11'
cache: 'pip'

- name: Show tool versions
run: |
python --version
pip --version
bash --version | head -n 1

- name: Normalise executable permissions from manifest
run: bash 00_TOOLS/qa/apply_permissions.sh

- name: Check executable permissions
run: bash 00_TOOLS/qa/check_executability.sh

- name: Run Markdown link checker
run: python 00_TOOLS/qa/check_markdown_links.py

- name: Run language & lexical integrity check (teaching corpus)
run: |
python - <<'PY'
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile

src = Path('.').resolve()
ignored_names = {
'.git',
'.github',
'__pycache__',
'.pytest_cache',
'.mypy_cache',
'node_modules',
'.venv',
'venv',
}

with tempfile.TemporaryDirectory(prefix='compnet-integrity-') as td:
dst = Path(td) / 'repo'

def ignore(path, names):
ignored = {name for name in names if name in ignored_names}
if Path(path).resolve() == src:
ignored.add('CHANGELOG.md')
return ignored

shutil.copytree(src, dst, ignore=ignore)
subprocess.run([sys.executable, '00_TOOLS/qa/check_integrity.py'], cwd=dst, check=True)

print('Integrity check passed on teaching corpus (root CHANGELOG.md intentionally excluded as an audit delta document).')
PY

- name: Validate lecture figure targets
run: python 00_TOOLS/qa/check_fig_targets.py --puml-only

- name: Run pytest (if present)
shell: bash
run: |
set -euo pipefail

if find . -type f \( -name 'test_*.py' -o -name '*_test.py' \) -print -quit | grep -q .; then
python -m pip install --upgrade pip
python -m pip install 'pytest<9' pyyaml
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest -q
else
echo 'No pytest tests detected, skipping.'
fi
cache-dependency-path: |
00_TOOLS/qa/requirements.txt
03_LECTURES/tests/requirements.txt
- name: Set up Node for HTML control-logic tests
uses: actions/setup-node@v4
with:
node-version: '24'
- name: Install QA dependencies
run: python -m pip install -r 00_TOOLS/qa/requirements.txt
- name: Check source and component regressions
run: python 00_TOOLS/qa/run_checks.py
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,8 @@ build/

# Large binaries fetched later
00_TOOLS/plantuml.jar

# Local formative assessment results (keep the documentation).
00_APPENDIX/a)PYTHON_self_study_guide/formative/results/quiz_results_*.json

.venv-qa/
35 changes: 22 additions & 13 deletions 00_APPENDIX/LIVE_CODING_INSTRUCTOR_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Live coding is a teaching technique where the instructor **writes code in real t

---

## 2. Session Structure (15-20 minutess)
## 2. Session Structure (15-20 minutes)

```
┌─────────────────────────────────────────────────────────────────────────────┐
Expand Down Expand Up @@ -134,13 +134,20 @@ sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
# STEP 1: "Let's see if Docker responds"
import subprocess

# QUESTION: "What command checks if Docker is running?"
result = subprocess.run(['docker', '--version'], capture_output=True, text=True)
print(f"Docker version: {result.stdout.strip()}")

# PLANNED MISTAKE: Run without sudo service docker start
# "Cannot connect to Docker daemon"
# "What do we need to do after restarting Windows?"
# QUESTION: "Which command contacts the Docker daemon rather than only the CLI?"
try:
result = subprocess.run(['docker', 'info'], capture_output=True, text=True, timeout=15)
print("Daemon accessible" if result.returncode == 0 else "Daemon inaccessible")
if result.returncode:
print(result.stderr.strip())
except FileNotFoundError:
print("Docker CLI is not installed")
except subprocess.TimeoutExpired:
print("Docker daemon check timed out")

# PLANNED MISTAKE: use an explicitly manual-start WSL setup with Docker stopped.
# A systemd-enabled distribution or Docker Desktop may start its daemon automatically.
# Inspect docker context, service state and access permissions before changing them.

# STEP 2: "Let's run a simple container"
# QUESTION: "What does 'docker run --rm' do?"
Expand All @@ -164,8 +171,10 @@ def check_port(host, port):
return False

# QUESTION: "What port does Portainer listen on?"
portainer_ok = check_port('localhost', 9000)
print(f"Portainer accessible: {portainer_ok}")
portainer_ok = check_port('localhost', 9050)
print(f"TCP listener on the configured Portainer port: {portainer_ok}")
# A TCP connection does not establish HTTP readiness or successful authentication.
# Open the configured URL and verify the Portainer page separately.

# RECAP
# "We verified: Docker installed, daemon running, container functional, Portainer up"
Expand Down Expand Up @@ -265,7 +274,7 @@ server.listen(1)
- "What happens if the client disconnects?"

### Questions requiring postponement:
- "How does TLS work?" → "Excelslow question! We'll cover it in Week 10."
- "How does TLS work?" → "Excellent question! We'll cover it in Week 10."

### Off-topic questions:
- "Can we do this in Rust?" → "Interesting, but let's focus on Python now. We'll chat at break."
Expand Down Expand Up @@ -313,7 +322,7 @@ server.listen(1)

### Before next session
- [ ] Have I published code for students?
- [ ] Have I updatad slides with clarifications?
- [ ] Have I updated slides with clarifications?
- [ ] Have I prepared supplementary exercises for difficult concepts?
- [ ] Have I reviewed timing (too fast / too slow)?

Expand All @@ -339,7 +348,7 @@ server.listen(1)
### "A student asks questions continuously and derails the course"

```
- "Excelslow question, but let's discuss at break to not lose the thread"
- "Excellent question, but let's discuss at break to not lose the thread"
- Visibly note the question on the board
- Return to it if relevant later
```
Expand Down
28 changes: 14 additions & 14 deletions 00_APPENDIX/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,12 @@
# make export - Export quiz to all formats
# make clean - Clean generated files

.PHONY: help quiz test lint validate export clean verify all
.PHONY: help quiz quiz-review quiz-random quiz-validate test test-verbose test-exports test-all lint lint-fix validate validate-python validate-yaml validate-json export export-json export-moodle export-qti clean verify all

# Configuration
PYTHON := python3
QUIZ_DIR := formative
EXAMPLES_DIR := PYTHON_self_study_guide/examples
EXAMPLES_DIR := a)PYTHON_self_study_guide/examples
TESTS_DIR := $(EXAMPLES_DIR)/tests

# Colours for output
Expand Down Expand Up @@ -90,20 +90,20 @@ quiz-validate:

test:
@echo "$(CYAN)Running smoke tests...$(NC)"
@$(PYTHON) $(TESTS_DIR)/test_smoke.py
@$(PYTHON) "$(TESTS_DIR)/test_smoke.py"
@echo "$(GREEN)✓ Smoke tests passed$(NC)"

test-verbose:
@echo "$(CYAN)Running smoke tests (verbose)...$(NC)"
@$(PYTHON) -m pytest $(TESTS_DIR)/test_smoke.py -v 2>/dev/null || $(PYTHON) $(TESTS_DIR)/test_smoke.py
@$(PYTHON) -m pytest "$(TESTS_DIR)/test_smoke.py" -v

test-exports:
@echo "$(CYAN)Running export function tests...$(NC)"
@if [ -f "$(QUIZ_DIR)/tests/test_quiz_exports.py" ]; then \
$(PYTHON) $(QUIZ_DIR)/tests/test_quiz_exports.py; \
$(PYTHON) $(QUIZ_DIR)/tests/test_quiz_exports.py || exit $$?; \
echo "$(GREEN)✓ Export tests passed$(NC)"; \
else \
echo "$(YELLOW)⚠ Export tests not found$(NC)"; \
echo "$(RED)Export tests not found$(NC)"; exit 1; \
fi

test-all: test test-exports
Expand All @@ -116,19 +116,19 @@ test-all: test test-exports
lint:
@echo "$(CYAN)Running linter...$(NC)"
@if command -v ruff >/dev/null 2>&1; then \
ruff check $(EXAMPLES_DIR)/*.py $(QUIZ_DIR)/*.py --ignore E501; \
ruff check "$(EXAMPLES_DIR)"/*.py $(QUIZ_DIR)/*.py --ignore E501; \
elif command -v flake8 >/dev/null 2>&1; then \
flake8 $(EXAMPLES_DIR)/*.py $(QUIZ_DIR)/*.py --max-line-length=120; \
flake8 "$(EXAMPLES_DIR)"/*.py $(QUIZ_DIR)/*.py --max-line-length=120; \
else \
echo "$(YELLOW)⚠ No linter found. Install with: pip install ruff$(NC)"; \
$(PYTHON) -m py_compile $(EXAMPLES_DIR)/*.py $(QUIZ_DIR)/*.py; \
$(PYTHON) -m py_compile "$(EXAMPLES_DIR)"/*.py $(QUIZ_DIR)/*.py || exit $$?; \
echo "$(GREEN)✓ Syntax check passed$(NC)"; \
fi

lint-fix:
@echo "$(CYAN)Running linter with auto-fix...$(NC)"
@if command -v ruff >/dev/null 2>&1; then \
ruff check $(EXAMPLES_DIR)/*.py $(QUIZ_DIR)/*.py --fix --ignore E501; \
ruff check "$(EXAMPLES_DIR)"/*.py $(QUIZ_DIR)/*.py --fix --ignore E501; \
else \
echo "$(YELLOW)⚠ ruff not found. Install with: pip install ruff$(NC)"; \
fi
Expand All @@ -142,7 +142,7 @@ validate: validate-python validate-yaml validate-json

validate-python:
@echo "$(CYAN)Validating Python syntax...$(NC)"
@find . -name "*.py" -type f -exec $(PYTHON) -m py_compile {} \;
@$(PYTHON) -m compileall -q .
@echo "$(GREEN)✓ Python syntax valid$(NC)"

validate-yaml:
Expand All @@ -153,7 +153,7 @@ validate-yaml:
validate-json:
@echo "$(CYAN)Validating JSON files...$(NC)"
@if [ -f "$(QUIZ_DIR)/quiz.json" ]; then \
$(PYTHON) -c "import json; json.load(open('$(QUIZ_DIR)/quiz.json'))"; \
$(PYTHON) -c "import json; json.load(open('$(QUIZ_DIR)/quiz.json'))" || exit $$?; \
echo "$(GREEN)✓ JSON valid$(NC)"; \
else \
echo "$(YELLOW)⚠ quiz.json not found (optional)$(NC)"; \
Expand All @@ -163,7 +163,7 @@ validate-json:
# EXPORT TARGETS
#═══════════════════════════════════════════════════════════════════════════════

export: export-json export-moodle
export: export-json export-moodle export-qti
@echo "$(GREEN)✓ All exports completed$(NC)"

export-json:
Expand Down Expand Up @@ -204,7 +204,7 @@ clean:
@find . -type f -name "*.pyc" -delete 2>/dev/null || true
@find . -type f -name "*_export.json" -delete 2>/dev/null || true
@find . -type f -name "*_moodle.gift" -delete 2>/dev/null || true
@find . -type f -name "*_qti.xml" -delete 2>/dev/null || true
@find . -type f \( -name "*_qti.xml" -o -name "*_qti.zip" \) -delete 2>/dev/null || true
@echo "$(GREEN)✓ Clean completed$(NC)"

#═══════════════════════════════════════════════════════════════════════════════
Expand Down
62 changes: 62 additions & 0 deletions 00_APPENDIX/a)PYTHON_self_study_guide/CANONICAL_LAB_MAP.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Python self-study: canonical COMPNET-EN paths

Use this map with the [Python guide](PYTHON_NETWORKING_GUIDE.md) and its ten HTML
modules. Run terminal commands from the **repository root inside the Linux VM or
selected WSL environment**. A slide's Simulate/Show output control displays a
prepared teaching illustration; it does not execute Python or generate a capture.

| Module | Real source or entry point | What to inspect or run |
|---|---|---|
| 1–2: setup and reading | [05_ping_latency.py](examples/05_ping_latency.py) | Dataclass, argparse, subprocess result and bounded failure handling |
| 3: bytes and text | [02_bytes_vs_str.py](examples/02_bytes_vs_str.py) | Encoding, decoding and temporary-file ownership |
| 4: sockets | [01_socket_tcp.py](examples/01_socket_tcp.py), [S02](../../04_SEMINARS/S02/) | Separate server/client processes and the actual protocol handout |
| 5: organisation | [03_struct_parsing.py](examples/03_struct_parsing.py) | Importable functions, IPHeader dataclass and main guard |
| 6: CLI | [05_ping_latency.py](examples/05_ping_latency.py), [lab runner](../../00_TOOLS/lab_runner/) | The actual --help and documented arguments |
| 7: packet analysis | [S07](../../04_SEMINARS/S07/), [PCAP tools](../../00_TOOLS/pcap/) | Capture privileges, interfaces and parsed fields |
| 8: concurrency | [S03 multi-client server](../../04_SEMINARS/S03/S03_Part01_Example_TCP_Multi_client_Server.py) | Client lifetime, framing and concurrency |
| 9: HTTP | [S08](../../04_SEMINARS/S08/), [C10 scenarios](../../03_LECTURES/C10/) | HTTP framing, request/response bytes and proxy behaviour |
| 10: debugging | [04_error_handling.py](examples/04_error_handling.py), [tests](examples/tests/) | Resource ownership, errors and component regression evidence |

## First runnable checks

```bash
cd "$HOME/COMPNET-EN"
python3 "00_APPENDIX/a)PYTHON_self_study_guide/examples/05_ping_latency.py" --host 127.0.0.1 --count 3
python3 "00_APPENDIX/a)PYTHON_self_study_guide/examples/02_bytes_vs_str.py"
python3 "00_APPENDIX/a)PYTHON_self_study_guide/examples/03_struct_parsing.py"
```

The ping helper needs Linux `ping` (iputils-ping). A missing command, unsuccessful
reply or unparsed RTT produces a non-zero exit. Report those observations rather
than substituting the slide's example timings.

For the socket example, use two Linux terminals in the repository root:

```bash
# Terminal A: stop with Ctrl+C after the experiment.
python3 "00_APPENDIX/a)PYTHON_self_study_guide/examples/01_socket_tcp.py" server 9090
```

```bash
# Terminal B
python3 "00_APPENDIX/a)PYTHON_self_study_guide/examples/01_socket_tcp.py" client 127.0.0.1 9090 "Test"
```

For subnetting, the C05 calculator accepts a positional address/prefix:

```bash
python3 03_LECTURES/C05/assets/scenario-cidr-basic/cidr-calc.py 192.168.23.233/24
```

Do not assume every course script implements argparse or a common `--mode` option.
The S04 text framing, binary framing and pickle-based UDP exercise are defined by
[S04's source and handouts](../../04_SEMINARS/S04/). Generic JSON, checksum and package
sketches in this Python guide are separate learning examples.

## Provenance

Earlier versions of these optional materials referred to the external netROwsl kit.
The v1.5.0 revision maps learning activities to COMPNET-EN while retaining the Python
concepts. Repository v1.4.0 preserves the prior text. The VM remains
[MININET-SDN 1.0.0](https://doi.org/10.5281/zenodo.24289763); see
[environment routes](../docs/environment_routes.md) for installation and Portainer.
20 changes: 7 additions & 13 deletions 00_APPENDIX/a)PYTHON_self_study_guide/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
.DEFAULT_GOAL := help

# Python interpreter
PYTHON := python3
PYTHON := $(if $(wildcard .venv/bin/python),.venv/bin/python,python3)

# Directories
QUIZ_DIR := formative
Expand Down Expand Up @@ -224,14 +224,7 @@ test: test-all

test-all:
@echo "$(COLOUR_BOLD)Running all tests...$(COLOUR_RESET)"
@if command -v pytest >/dev/null 2>&1; then \
pytest $(TESTS_DIR)/ -v; \
else \
$(PYTHON) -m pytest $(TESTS_DIR)/ -v 2>/dev/null || \
($(PYTHON) $(TESTS_DIR)/test_smoke.py && \
$(PYTHON) $(TESTS_DIR)/test_bytes_vs_str.py && \
$(PYTHON) $(TESTS_DIR)/test_struct_parsing.py); \
fi
@$(PYTHON) -m pytest $(TESTS_DIR)/ -v

test-smoke:
@echo "$(COLOUR_BOLD)Running smoke tests...$(COLOUR_RESET)"
Expand Down Expand Up @@ -270,10 +263,11 @@ check:
@echo "$(COLOUR_GREEN)Environment check complete.$(COLOUR_RESET)"

install:
@echo "$(COLOUR_BOLD)Installing dependencies...$(COLOUR_RESET)"
@pip install --user pyyaml pytest 2>/dev/null || \
pip install pyyaml pytest --break-system-packages || \
echo "$(COLOUR_YELLOW)Please install: pip install pyyaml pytest$(COLOUR_RESET)"
@echo "Creating a local virtual environment for this guide..."
@python3 -m venv .venv
@.venv/bin/python -m pip install 'PyYAML==6.0.3' 'pytest==8.4.2'
@echo "Done. Make targets now use .venv/bin/python; activate it with: source .venv/bin/activate"


lint:
@echo "$(COLOUR_BOLD)Checking code style...$(COLOUR_RESET)"
Expand Down
Loading
Loading