Kmom10: Projekt och examination

Öppna terminalen och flytta dig till din kursmapp och kör följande kommando för att skapa katalogerna som används i kmom10. Ladda också ner de senaste testerna:

cd dbwebb-kurser/python-<akronym> # ersätt <akronym> med din akronym
uv run task download-all
uv run task create-src-dirs

Tips innan du börjar med projektet, repetera vad du har gjort i tidigare kursmoment. Fräscha upp minnet, tänk på hur långt du har kommit och hur mycket du har lärt dig.

Läs först igenom hela projektet och lägg upp en plan. Vad ska du göra? Hur kan du göra det? Har du gjort något liknande delproblem tidigare? Därefter börjar du koda.

Detta kursmoment avslutar och examinerar kursen.

Du jobbar enskilt och tar inte hjälp av någon. Det du lämnar in är ditt eget arbete och du har inte låtit en Ai-bot göra ditt jobb.

Förberedelser

Har du skapat en branch för kmom10 bth/submit/kmom10? Du kontrollerar det med git branch i terminalen och på GitHub, se Kontrollera nya branchen för mer info.

Om du missat det, gör det nu.

git checkout -b bth/submit/kmom10 && git push origin bth/submit/kmom10
git checkout main
git branch # ok om stjärnan är framför main

Upplägget är enligt följande

Projektet ska utföras individuellt
Tänk på att namngivning ska ske på engelska. Varje namn som är på annat språk ger poängavdrag.
Variabler som innehåller konstanter ska vara namngivna som konstanter.
Du ska implementera koden med konstruktioner du har lärt dig i kursen. Alltså ska du t.ex. inte använda klasser.
- Du får bara använda moduler som vi har gått igenom i kursen, time-modulen, samt random-modulen (enbart i krav 6).
- Du får inte använda:
  - zip() funktionen
  - list/dict comprehension/generators
  - lambda funktioner
- Om du är osäker, fråga kursansvarig!

Du kan själv styra din arbetsinsats genom att välja vilka valfria delar du utför.

Förutsättning

Du har jobbat igenom kmom01-kmom06 (och lämnat in dem). Det finns ingen anledning att påbörja projektet innan du är klar med kmom06.

Bedömning och betygsättning

Det finns ett dokument som beskriver grunderna för bedömning och betygsättning av projektet och kursen som helhet.

Projektidé och upplägg

Du ska bygga ett quiz-program som körs i terminalen. Programmet läser in frågor från textfiler, presenterar dem en åt gången med fyra svarsalternativ och räknar ut hur bra det gick när quizet är klart. Varje fråga tillhör en kategori och är värd ett visst antal poäng.

Det finns valfria delar som du kan välja att göra för att öka dina chanser till ett högre betyg.

Projektspecifikation

Utveckla och leverera projektet enligt följande specifikation. Saknas info i specen kan du själv välja väg och dokumentera dina val i redovisningstexten.

I grundkraven ska det finnas fyra menyval:

1. Starta quiz med filen easy.txt
2. Starta quiz med filen medium.txt
3. Starta quiz med filen hard.txt
4. Visa topplistan från scores.txt
q. Avsluta programmet

Generell struktur

Koden ska ligga i src/kmom10/quiz.

Skapa filen main.py som ska vara startpunkt för programmet.
Du måste skapa minst en till modul att dela upp din kod i.
Skapa mappen questions i quiz-mappen och lägg dina frågefiler där.
Din kod ska vara DRY.
Endast konstanter får ligga som globala variabler.
Programmet ska kunna köras från quiz-mappen. Det ska inte krascha om du står i quiz och startar programmet.
Koden ska validera med Ruff.
Testerna som finns ska passera.

Väl fungerande program

Programmet ska fungera utan brister och inte krascha när man använder det enligt kraven.

Programmet ska hantera ogiltiga menyval utan att krascha.
Programmet ska hantera ogiltiga svar i quizet utan att krascha (t.ex. om användaren skriver E eller 1 istället för A–D).
Programmet ska inte krascha om scores.txt saknas eller är tom.

Frågefilernas format

Frågorna ligger i textfiler med en fråga per block. Varje fråga består av nio rader och blocken separeras med en blank rad.

<kategori>
<frågetext>
<alternativ A>
<alternativ B>
<alternativ C>
<alternativ D>
<rätt svar: A, B, C eller D>
<poängvärde: positivt heltal>
<ledtråd>

Exempel på en frågefil med två frågor:

Geografi
Vad är Sveriges huvudstad?
Oslo
Stockholm
Köpenhamn
Helsinki
B
3
Stockholm ligger vid Mälaren och Östersjön.

Historia
Vilket år bildades Kungariket Sverige officiellt?
829
1000
972
1523
C
2
Det skedde under 900-talet.

scores.txt

Filen skapas om den inte finns.

Filen ska ligga i quiz/-mappen, alltså på samma nivå som main.py.

För varje quiz som genomförs ska du spara: namn, svårighetsgrad, totala poäng, poängprocent och tid i sekunder. Använd ett lämpligt format som gör det enkelt att läsa in och skriva ut topplistan.

Krav 1: Quiz

Menyval 1–3 startar ett quiz med respektive frågefil (easy.txt, medium.txt, hard.txt).

Ett quiz

Läs in alla frågor från vald fil.
Visa frågorna en i taget. Visa alltid frågans kategori och vilket frågenummer det är av totalt.
För varje fråga:
- Visa frågans text och de fyra svarsalternativen märkta A–D.
- Läs in användarens svar. Svar är case-insensitive (a och A är likvärdiga). Om svaret inte är A, B, C eller D — be användaren svara igen tills ett giltigt svar ges.
- Tala om för användaren om svaret var rätt eller fel och hur många poäng de fick.
Visa slututskriften när alla frågor är besvarade.
Be användaren skriva in sitt namn och spara resultatet i scores.txt.
Efter att resultatet sparats, visa ett meddelande och be användaren trycka Enter för att återgå till menyn.

Poäng

Rätt svar ger frågans fulla poängvärde.
Fel svar ger 0 poäng.

Kategorier

Håll koll på hur det gick per kategori. Spåra antalet rätta svar och totalt antal frågor per kategori. Skriv ut en kategorisammanfattning i slututskriften.

Slututskrift

Slututskriften ska innehålla:

Antal rätta svar på formatet X/Y.
Poängprocent: (totalpoäng / maxpoäng) * 100, avrundat till en decimal med procenttecken.
Kategorisammanfattning: en rad per kategori med antal rätta svar och totalt antal frågor.
Tid (läggs till i krav 3).

Exempel på slututskriften (utan tid):

Resultat: 1/2 rätta svar
Poäng: 2/5 (40.0%)

Kategorier:
Geografi        : 0/1
Historia        : 1/1

Krav 2: Topplista

Menyval 4 skriver ut resultaten från scores.txt.

Utskriften ska vara grupperad på svårighetsgrad.
Inom varje grupp sorteras poster på poängprocent i fallande ordning i första hand och tid i andra hand.
Programmet ska inte krascha om scores.txt saknas — visa ett lämpligt meddelande istället. *. Efter att topplistan visats be användaren trycka Enter för att återgå till menyn.

Exempel:

Easy:
Andreas         40.0%    2p    34.75s
Sara            20.0%    1p    22.10s

Hard:
Sara           100.0%    5p    18.22s

Krav 3: Tid

Lägg till tidmätning med modulen time.

Mät per fråga: från att frågan visas tills att användaren skickar sitt svar.
Mät också total tid för hela quizet.
Visa tid direkt efter varje svar.
Inkludera total tid i slututskriften.

Tidsvärdena behöver inte avrundas i utskriften.

Uppdaterad slututskrift (med tid):

Resultat: 1/2 rätta svar
Poäng: 2/5 (40.0%)
Total tid: 10.47 sekunder

Kategorier:
Geografi        : 0/1
Historia        : 1/1

Exempel

Nedanstående exempel visar ett quiz med frågorna från frågefilernas format. Dina utskrifter behöver inte vara identiska, men de måste innehålla samma information och korrekta beräkningar.

>>> markerar vad användaren skriver in.

1. Starta quiz med filen easy.txt
2. Starta quiz med filen medium.txt
3. Starta quiz med filen hard.txt
4. Visa topplistan från scores.txt
q. Avsluta programmet

Menyval: >>> 1

--- Fråga 1 av 2 ---
Kategori: Geografi
Vad är Sveriges huvudstad?

A. Oslo
B. Stockholm
C. Köpenhamn
D. Helsinki

Ditt svar: >>> A
Fel! Rätt svar var B. Du fick 0/3 poäng.
Tid: 4.32 sekunder

--- Fråga 2 av 2 ---
Kategori: Historia
Vilket år bildades Kungariket Sverige officiellt?

A. 829
B. 1000
C. 972
D. 1523

Ditt svar: >>> C
Rätt! Du fick 2/2 poäng.
Tid: 6.15 sekunder

Resultat: 1/2 rätta svar
Poäng: 2/5 (40.0%)
Total tid: 10.47 sekunder

Kategorier:
Geografi        : 0/1
Historia        : 1/1

Skriv in ditt namn: >>> Andreas

Resultatet har sparats. Tryck Enter för att återgå till menyn.

Krav 4 (valfritt) 10p: Quiz-sammanfattning

Lägg till en detaljerad sammanfattning som visas efter slututskriften men innan användaren skriver in sitt namn.

Sammanfattningen ska visa en rad per fråga med:

Frågans text — trunkerad till 30 tecken om den är längre (lägg till ... om den trunkeras).
Användarens svar (bokstaven A–D).
Rätt svar (bokstaven A–D).
Poäng erhållna och frågans maxpoäng.

Exempel:

--- Sammanfattning ---
Vad är Sveriges huvudstad?...    Ditt svar: A    Rätt: B    Poäng: 0/3
Vilket år bildades Kungarik...   Ditt svar: C    Rätt: C    Poäng: 2/2

Krav 5 (valfritt) 10p: Ledtrådar

Låt användaren begära en ledtråd under ett quiz.

Innan användaren svarar på en fråga kan de skriva ? för att visa ledtråden.
Att använda ledtråden kostar halva frågans poängvärde avrundat nedåt. Exempel: en fråga värd 3 poäng kostar 1 poäng i ledtrådsavgift, en fråga värd 4 poäng kostar 2 poäng.
Minimum är 0 poäng per fråga — en ledtrådsavgift kan aldrig ge minuspoäng.
Varje fråga kan bara ha en ledtråd. Om användaren skriver ? igen visas ledtråden utan extra avgift.
I slututskriften: visa totalt antal använda ledtrådar.

Exempel:

Ditt svar (eller ? för ledtråd): >>> ?
Ledtråd: Stockholm ligger vid Mälaren och Östersjön.

Ditt svar (eller ? för ledtråd): >>> A
Fel! Rätt svar var B. Du fick 0/3 poäng. (Ledtråd använd, kostnad: 1 poäng)

Krav 6 (valfritt) 10p: Slumpmässigt quiz

Lägg till menyval 5: Slumpmässigt quiz.

Användaren anger hur många frågor quizet ska innehålla.
Frågorna väljs slumpmässigt från alla tre filerna kombinerade (easy.txt, medium.txt, hard.txt). Ingen fråga ska förekomma mer än en gång i samma quiz.
Om användaren anger fler frågor än vad som finns tillgängligt körs quizet med alla tillgängliga frågor.
Resultatet sparas i scores.txt med svårighetsgraden random.
Du får använda modulen random enbart för detta krav.

Krav inlämning

När du är klar taggar du ditt repo (v10.0.0 eller högre) och pushar till GitHub.
Skapa den branch som ska användas för nästa inlämning. Stå i kursmappen i terminalen och kör följande kommando:
Terminal window
```
git branch -c bth/submit/kmom10
git push -u origin bth/submit/kmom10
```
När allt är klart och fungerar gör du en pull request (PR) mot branchen bth/submit/kmom10. Du kan följa instruktionerna i Gör en Pull Request fast använd branchen bth/submit/kmom10.

Redovisning

Svara på följande frågor i din redovisningstext för kmom10 i README.md.

Skriv ett allmänt stycke om hur projektet gick att genomföra. Problem/lösningar/strul/enkelt/svårt/snabbt/lång tid, etc. Var projektet lätt eller svårt? Tog det lång tid? Vad var svårt och vad gick lätt? Var det ett bra och rimligt projekt för denna kursen?
Vilka valfria delar gjorde du? Varför? Hur gick det?
Vilken är din TIL för detta kmom?
Vilken är din TIL för kursen som helhet?
(Valfritt) Avsluta med ett sista stycke med dina tankar om kursen och vad du anser om materialet och handledningen. Återkoppla till lärarteamet och förslå eventuella förbättringsförslag till kommande kurstillfällen.
(Valfritt) Är du nöjd/missnöjd? På en skala 1-10, vilket betyg ger du kursen?

Redovisningsvideo

Du skall förbereda och utföra en slutpresentation av ditt projekt. Du kan läsa hur du kan förbereda dig i dokumentet “Planera din slutpresentation”. Läs mer om hur du kan spela in en redovisningsvideo med OBS.

När du gör din video tänk på att det vi vill se är att du har skrivit koden och att du förstår vad den gör.

Lägg en länk till videon som en kommentar i din PR.
Detta kan du göra dagen efter projektets deadline.
Videon ska vara 5-8 minuter lång.
Vi kan begära att du gör ett muntligt förhör om vi är osäkra på om du kan/har skrivit koden.