In deze tutorial leer je hoe je een vervuilde dataset opschoont voor je er analyses op los laat.

In de praktijk zijn datasets namelijk zelden perfect gestructureerd. Je komt vaak missende waarden tegen, duplicaten in je data, of verkeerde data types die analyses onmogelijk maken. In deze tutorial leer je hoe je deze problemen oplost met pandas. Je ontdekt hoe je missende waarden detecteert en behandelt met dropna() en fillna(), duplicaten opspoort en verwijdert, en data types controleert en converteert naar het juiste formaat.

Veel lees- en leerplezier!

Naar de tutorial

In korte, duidelijke video's legt Nicky de basisprincipes van programmeren uit, zoals variabelen, datatypes en functies. Je hebt geen technische of wiskundige voorkennis nodig. Met slechts 1 tot 3 uur per week kun je in zes weken al je eerste Python-scripts schrijven. Mocht je ergens vastlopen of vragen hebben, dan staat er een besloten online community klaar om je te ondersteunen.

Of je nu je digitale vaardigheden wilt verbeteren, een carrièreswitch overweegt of gewoon iets nieuws wilt leren, deze cursus is een uitstekende start. Nicky's aanpak maakt programmeren begrijpelijk en leuk voor iedereen.

Bekijk het aanbod van NK Academy

Django biedt een krachtig systeem om gegevens in een database op te slaan en te beheren via models. In deze tutorial leer je hoe je models definieert, migraties uitvoert om je database structuur te creëren, en de Django Admin gebruikt om gegevens toe te voegen. Je leert ook hoe je met queries data uit je database haalt om in je templates te tonen.

Ben je geïnteresseerd in het maken van een webapplicatie in Python, bekijk de reeks dan zeker!

Naar Werken met een database in Django

Naar de reeks

Een voorbeeld van een (klein) JSON-bestandje is:

[
   {
      "Naam":"JSON",
      "Type":"Gegevensuitwisselingsformaat",
      "isProgrammeertaal":false,
      "Zie ook":[
         "XML",
         "ASN.1"
      ]
   },
   {
      "Naam":"JavaScript",
      "Type":"Programmeertaal",
      "isProgrammeertaal":true,
      "Jaar":1995
   }
]

Je ziet: dit lijkt erg op een lijst met twee dictionaries! Het voordeel van JSON is dat het zowel door computers goed leesbaar is, maar voor mensen ook.

Op python-cursus.nl vind je de reeks Werken met JSON. Werk je met API’s of wil je dit gaan doen, dan is het zeker de moeite waard om deze reeks eens te bekijken!

Lees Werken met JSON

Succes!

Hoe zorg je er dan voor dat je op een veilige manier kunt experimenteren? Of hoe zorg je ervoor dat alle collega's aan dezelfde code kunnen werken, zonder elkaar in de weg te zitten? En hoe zorg je er vervolgens voor dat alle wijzigingen weer worden samengevoegd?

Daar komt versiebeheer om de hoek kijken. Het meestgebruikte versiebeheersysteem in de softwareontwikkeling is Git. In deze nieuwe reeks leer je de basis van het werken met Git, inclusief het werken in verschillende branches en hoe je jouw werk op een centrale plek kunt opslaan, zodat je collega’s er ook bij kunnen.

Bekijk de reeks 'Werken met Git'

Lees deze tutorial ook op python-cursus.nl

In de vorige tutorial leerde je over de basis van templates in Django. In deze tutorial ga je een stap verder en ga je context toevoegen. De context is een dict die je mee kunt geven aan een template. Hiermee kun je allerlei gegevens beschikbaar maken in je template, bijvoorbeeld een lijst om over te itereren.

Aan het eind van deze tutorial heb je de overview-template uit de vorige tutorial uitgebreid met een lijst met auto's die je (al dan niet fictief) in je bezit hebt, en met je naam. Dat ziet er ongeveer zo uit:

Open je autotracker-project en activeer de venv.

cd ~/projects/autotracker
source .venv/bin/activate  # .venv\Scripts\activate.bat voor Windows

Auto objecten maken

Een context is in de context (ha ha) van templates een dict met objecten. Dat kan eigenlijk van alles zijn, en het hangt helemaal van je applicatie af wat een logische context is. In het geval van AutoTracker is een belangrijk object natuurlijk de auto. Om de context te demonstreren, ga je de overview-pagina uitbreiden met auto's die je momenteel in je bezit hebt.

Dat ga je eerst nog op een statische manier doen. Later in deze reeks zul je gaan werken met een database waarin je auto's zijn opgeslagen. Maar voor nu volstaat het om enkele objecten handmatig aan te maken.

Dat kan op verschillende manieren. Gebruik voor nu een dataclass. Als je nog niet bekend met dataclasses, een dataclass is een speciale klasse, waarmee je op vereenvoudigde wijze gegevens kunt opslaan. Ideaal dus als je vooral met gegevens wilt werken, en niet zozeer met logica.

Een dataclass voor een auto maak je als volgt aan:

from dataclasses import dataclass

@dataclass
class Car:
    name: str
    purchase_price: int
    purchase_year: int
    construction_year: int
    fuel_type: str
    km_at_purchase: int

Je ziet dat je klasse-attributen en type hints gebruikt om een dataclass op te bouwen. Het is een verkorte manier voor:

class Car:
   def __init__(self, name: str, purchase_price: int, purchase_year: int, 
                construction_year: int, fuel_type: str, km_at_purchase: int):
       self.name = name
       self.purchase_price = purchase_price 
       self.purchase_year = purchase_year
       self.construction_year = construction_year
       self.fuel_type = fuel_type
       self.km_at_purchase = km_at_purchase

In de Basiscursus Python lees je nog eens over het werken met klassen. In Werken met Pythons Typesysteem en Type Hints lees je nog eens over het werken met types.

Plaats de Car-klasse in het bestand models.py, in de tracker-map. In latere tutorials leer je wat 'echte' models zijn en hoe je ermee werkt, voor nu volstaat deze dataclass.

De volgende stap is om een aantal auto's te maken. Je kunt je eigen auto('s) invoeren, maar je kunt er ook een paar bedenken. Maak er in elk geval meer dan één. Doe dit in de functie overview in tracker/views.py. Vergeet niet de Car-klasse te importeren.

from tracker.models import Car

def overview(request):

    leaf = Car(
        name="Nissan Leaf",
        purchase_price=12000,
        purchase_year=2024,
        construction_year=2018,
        fuel_type="Electric",
        km_at_purchase=90000
    )

    ford = Car(
        name="Ford Focus Wagon",
        purchase_price=10000,
        purchase_year=2023,
        construction_year=2018,
        fuel_type="Gas",
        km_at_purchase=120000
    )


    return render(request, "overview.html")

Auto's aan de context toevoegen

Je hebt nu een aantal auto's aangemaakt in de overview-functie, maar hiermee zijn ze nog niet beschikbaar in je templates. Daarvoor voeg je ze eerst toe als context. Een context is een eenvoudige dict met objecten, in dit geval de auto's. Het toevoegen van de context doe je in twee stappen.

Maak eerst een dict genaamd context aan, met als sleutel "cars" en als waarden een lijst met je zojuist aangemaakte auto's. Je hoéft deze dict overigens geen context te noemen, maar het is wel zo duidelijk om dat wel te doen.

Vervolgens geef je deze dict mee aan de render-functie.

from tracker.models import Car

def overview(request):

    leaf = Car(
        ...
    )

    ford = Car(
        ...
    )

    context = {
        "cars": [leaf, ford]
    }

    return render(request, "overview.html", context=context)

En dat is het! In je template is "cars" nu beschikbaar als variabele. Hoe dat werkt, zie je zo. Om te laten zien dat je van alles aan een context kunt toevoegen, kun je de dict nog met iets (willekeurigs) uitbreiden. Bijvoorbeeld je naam:

context = {
    "cars": [leaf, ford],
    "name": "Erwin Matijsen"
}

De context in een template gebruiken

Je hebt nu een context beschikbaar gemaakt aan je template. De sleutels van je dict worden beschikbaar als variabelen in je template. In dit geval heb je dus twee variabelen tot je beschikking in je overview-template: cars en name. Maar hoe gebruik je deze variabelen nu in je template?

Variabelen

Dit doe je op de eenvoudigste manier met de syntax voor variabelen: {{ <variabele> }}. Voeg aan overview.html bijvoorbeeld het volgende toe:

{% extends "base.html" %}

{% block main %}
    <h1>Overzicht</h1>
    <hr/>

    <p>Hallo, {{ name }}. Dit zijn je auto's: </p>
    <p>{{ cars }}</p>

{% endblock main %}

Je ziet dat je {{ name }} en {{ cars }} kunt gebruiken. Herlaad de pagina, en je zult zien dat je de waarde ziet die je aan de context hebt toegevoegd met de sleutel name. Daar waar je {{ cars }} hebt toegevoegd, zie je een (niet zo mooie) lijst met je Car-objecten.

Template tags

Dat werkt, maar is niet zo mooi natuurlijk. Het zou mooier zijn als je een nette lijst zag met de namen van de auto's en bijvoorbeeld het aanschafjaar erachter. Dit doe je met de for-template tag. Template tags heb je al eerder gebruikt, namelijk {% extends "base.html" %} en {% block main %}. Misschien herken je de syntax al voor de meeste template tags: {% ... %}.

De for-template tag is iets uitgebreider. Het werkt vergelijkbaar als een for-loop in Python. Verander je template naar het volgende:

{% extends "base.html" %}

{% block main %}
    <h1>Overzicht</h1>
    <hr/>

    <p>Hallo, {{ name }}. Dit zijn je auto's: </p>

    <ol>
    {% for car in cars %}
        <li>{{ car.name }} ({{ car.purchase_year }})</li>
    {% endfor %}
    </ol>

{% endblock main %}

Je begint de for-loop met {% for item in items %} en eindigt het met {% endfor %}. Dit plaats je tussen de <ol>-tags. Voor elk item in de cars-lijst zul je nu een <li>-element toevoegen, met de naam van de auto en tussen haakjes het jaar van aanschaf. In elke loop heb je een variabele car tot je beschikking. Om deze aan te roepen, plaats je het weer tussen {{ en }}. Omdat elke car een object van het type Car is, kun je de verschillende attributen aanroepen met de punt-notatie. Dus bijvoorbeeld car.name voor de naam en car.purchase_year voor het jaar van aanschaf.

Je kunt nog een kleine verbetering doorvoeren. Want wat als je (nog) geen auto's hebt toegevoegd? Hiervoor gebruik je de {% if ... %}-template tag.

{% if cars %}
    <ol>
    {% for car in cars %}
        <li>{{ car.name }} ({{ car.purchase_year }})</li>    
    {% endfor %}
    </ol>
{% else %}
    <p>Je hebt nog geen auto's toegevoegd</p>
{% endif %}

Hiermee toets je eerst of er een variabele cars is (of dat hij in elk geval niet leeg is). Als dit zo is, dan maak je de lijst met de {% for ... %}-constructie. Is er geen lijst met auto's, dan toon je een alternatieve tekst.

Maak de lijst in de context-dict maar eens leeg en kijk wat er in je template gebeurt als je de pagina herlaadt.

Probeer als oefening eens de lijst in de template uit te breiden met andere kenmerken van de auto's, zoals de kilometerstand bij aanschaf. Om het overzichtelijk te maken zou je het in een tabel kunnen plaatsen. Lees op MDN Web Docs hoe je een HTML tabel maakt.

Template filters

Naast template tags zijn er ook nog zogenaamde template filters. Met een template filter kun je waardes in een template wijzigen. Een simpel voorbeeld is de upper-filter, waarmee je een waarde omzet in kapitalen. Bijvoorbeeld de naam van je auto:

...
<li>{{ car.name|upper }} ({{ car.purchase_year }})</li>   
...

Je voegt |upper toe achter car.name. Een filter begint altijd met een |, gevolgd door de naam van het filter. Bij sommige filters is het ook nog mogelijk argumenten mee te geven, maar bij upper is dat niet het geval. Herlaad de pagina om te kijken of het werkt.

Conclusie

Je hebt gezien dat je op een eenvoudige manier je templates dynamisch kunt maken door een context toe te voegen. Een context is een dict met daarin items die je aan de template wilt toevoegen. Dit kan van alles zijn, van een eenvoudige str tot een uitgebreide lijst met complexe objecten.

Je roept een variabele in je template aan met {{ <variable> }}. Je kunt er ook over itereren met {% for ... %}. Dit zijn slechts de eerste stappen, met andere template tags en template filters is nog veel meer mogelijk. Maar de basis blijft gelijk. Zie de Django Documentatie voor meer template tags en template filters.

Lees deze tutorial ook op python-cursus.nl

Tussen al die al aanwezige sites had ik toch het idee dat er een bepaalde niche ontbrak, namelijk:

• Een site gericht op mensen die Python willen leren om hun werk eenvoudiger, efficiënter of slimmer te maken, maar waarvoor programmeren niet hun hoofdtaak is.

• En die Nederlandstalig is.

Zo gezegd, zo gedaan. De basiscursus publiceerde ik op basis.pythoncursus.nl en op 15 januari 2024 publiceerde ik het eerste bericht op python-cursus.nl.

De tutorials die ik schreef zijn vooral gericht op zaken die je handig kunt gebruiken in je werk, zoals het werken met pandas voor data-analyse. Of het werken met JSON, voor als je werkt met API's.

Inmiddels is 2024 voorbij en over een paar dagen is het precies een jaar geleden dat ik het eerste bericht plaatste. Een mooi moment om terug te blikken en te bepalen of python-cursus.nl inderdaad een bepaalde niche vult.

2024

Zoals de meeste sites houd ook ik de statistieken bij. Ik gebruik hiervoor Simple Analytics, een Nederlands alternatief voor Google Analytics met als onderscheidend kenmerk dat het privacy-vriendelijk is.

Een leuke feature is dat Simple Analytics ook een eigen API heeft, zodat je je eigen dashboards kunt maken. En dat is precies wat ik heb gedaan!

Op stats.python-cursus.nl kun je dit dashboard bekijken.

Het is een eenvoudige pagina, met een paar kernstatistieken over de website. Zo zie je dat er in 2024 bijna 1200 bezoekers waren, dat de tutorials over pandas populair zijn en dat de meeste bezoekers in het begin van de week (maandag t/m woensdag) komen. Misschien is dit laatste een (kleine) indicatie dat vooral mensen uit de beoogde doelgroep (werkenden) de site bezoeken...

Al met al vind ik de cijfers bemoedigend. Er is een niet-verwaarloosbaar aantal mensen dat python-cursus.nl weet te vinden en het nuttig vindt.

Iets dat me opviel is dat het bericht Moet ik nog leren programmeren met de opkomst van AI? één van de populairdere berichten is. Misschien niet heel gek, gezien de stormachtige opkomst van AI. Maar op een site met vooral tutorials toch opvallend. Misschien is er wel behoefte aan dit soort meer reflecterende berichten?

2025

De statistieken tonen in elk geval aan dat er voldoende behoefte is aan een Nederlandstalige site over het werken met Python. In 2025 ga ik dan ook zeker door met het schrijven van tutorials voor python-cursus.nl. De focus blijft uiteraard gericht op praktische toepassingen van Python voor mensen die het in hun werk kunnen inzetten. Een aantal onderwerpen die ik wil behandelen zijn in elk geval:

• De reeks over pandas uitbreiden

• Meer over werken met API's

• Meer over (werken met) AI

• De reeks over Django uitbreiden

Heb je nog andere onderwerpen die je graag behandeld zou willen zien, laat het me dan vooral weten.

Neem contact op

Ga naar de tutorial

De reeks zal in de toekomst nog worden uitgebouwd. Op de Series-pagina zie je welke tutorials er in deze reeks beschikbaar zijn.

Veel plezier en succes!

PS: Fun fact: python-cursus.nl zelf is ook gebouwd met Django!

In veel gevallen zul je niet met de hele DataFrame in één keer willen werken, maar wil je een selectie maken. Je hebt bijvoorbeeld maar enkele kolommen nodig, of juist alleen de rijen die voldoen aan een bepaalde voorwaarde. In deze tutorial leer je daarom hoe je gegevens uit een DataFrame kunt selecteren.

Voordat je begint

Om het selecteren te demonstreren, maak je gebruik van het project KNMI. Je kunt dit project bekijken op Github, zorg ervoor dat je voor deze tutorial de branch versie-3 bekijkt.

cd projects/knmi
source .venv/bin/activate  # .venv\Scripts\activate.bat voor Windows
git switch versie-3
python -m pip install --upgrade -r requirements

In het KNMI project download je data van het KNMI. Dit komt in een txt-bestand. Nadat je het tekstbestand hebt opgeslagen, schoon je het op en sla je het op als CSV-bestand, zodat er eenvoudiger mee is te werken. De data zijn maand- en jaargemiddelde temperaturen van het meetstation De Bilt.

Zorg ervoor dat je in main.py met de volgende code begint:

from data import clean_data, download, load_data

if __name__ == "__main__":
    # Download de gegevens
    try:
        download()
    except requests.exceptions.HTTPError as e:
        print("Error while downloading file:", e)

    # Schoon de gegevens op, sla op als CSV
    clean_data()

    # Laad de gegevens in een pandas DataFrame
    df = load_data()

In load_data() is de volgende code te vinden:

print(df.head(), "\n")

Hiermee toon je de eerste vijf rijen van de DataFrame, voor een snelle inspectie. Je kunt daar nog de volgende instructie aan toevoegen, voor een verdere inspectie:

print(df.info(), "\n")

Dit toont alle aanwezige kolommen, per kolom het aantal rijen met een waarde (non-null) en het dtype. In dit geval zijn alle kolommen int64 of float64.

Plaats alle verdere code in main.py in het if __name__ == "__main__"-blok. Je kunt het downloaden en opschonen van de gegevens één keer uitvoeren, en dan (tijdelijk) uitschakelen met comments.

Kolommen selecteren

De eenvoudigste manier om een bepaalde kolom te selecteren, is met []. Om bijvoorbeeld de kolom Jaargemiddelde te selecteren:

jaargemiddelde = df["Jaargemiddelde"]

Dit is herkenbaar, omdat het lijkt op hoe je bijvoorbeeld een waarde uit een dict ophaalt op basis van de sleutel. Echter, in de documentatie van pandas raden ze dit af. Ook een andere eenvoudige manier raden ze af:

jaargemiddelde = df.Jaargemiddelde

Voor snelle inspectie is dit prima, maar voor productiecode raden ze andere manieren aan.

loc

Met .loc gebruik je labels om kolommen en rijen te selecteren. In het geval van kolommen, is de label de kolomnaam. De algemene structuur van .loc is:

df.loc[row_indexer,column_indexer]

Om één of meer kolommen te selecteren waarbij je alle rijen wilt houden, gebruik je : op de plaats van de rij-selectie. Dus om de kolom "Jaargemiddelde" te selecteren:

jaargemiddelde = df.loc[:, "Jaargemiddelde"]

0       8.7
1       8.2
2       9.2
3       8.9
4       8.7
       ... 
119    11.7
120    10.5
121    11.6
122    11.8
123     NaN

Wil je nu meerdere kolommen selecteren, dan gebruik je een lijst met kolomnamen:

jaargemiddelde = df.loc[:, ["Jaar", "Jaargemiddelde"]]

     Jaar  Jaargemiddelde
0    1901             8.7
1    1902             8.2
2    1903             9.2
3    1904             8.9
4    1905             8.7
..    ...             ...
119  2020            11.7
120  2021            10.5
121  2022            11.6
122  2023            11.8
123  2024             NaN

Zou je "Jaar" en "Jaargemiddelde" omdraaien in de lijst, dan zijn de kolommen in de resulterende DataFrame ook omgedraaid.

Je kunt ook slicing toepassen. Stel dat je alle maandkolommen wilt selecteren:

maanden = df.loc[:, "Januari": "December"]

Het is hiervoor dus wel belangrijk dat je van tevoren je gegevens hebt geïnspecteerd, zodat je weet welke kolommen je precies selecteert die tussen "Januari" en "December" liggen. Let ook op dat, in tegenstelling tot gebruikelijk in Python, de slice tot en met is, dus ook "December" wordt geselecteerd.

Filteren

Je kunt .loc ook gebruiken met een lijst van booleans om tot een selectie te komen. Maak eerst een lijst met booleans. De volgende code kijkt of de "r" in de kolomnaam voorkomt. Let op dat je niet df gebruikt (de gehele dataset), maar maanden, de hiervoor aangemaakte DataFrame met enkel de maanden kolommen.

r_maanden = maanden.columns.str.contains("r")

[True  True  True  True False False False False  True  True  True  True]

Nu kun je deze lijst met booleans gebruiken in de selectie:

r_maanden = maanden.loc[:, r_maanden]

Of, in één stap:

r_maanden = maanden.loc[:, maanden.columns.str.contains("r")]

Let er altijd op dat de lengte van de lijst met booleans even lang is als het aantal kolommen. In dit geval bevat maanden 12 kolommen, en moet de lijst met booleans dus ook 12 lang zijn. Je kunt het zo zien: de lijst met booleans schuif je over de kolomnamen heen. Alle kolommen met True selecteer je (blijven behouden).

Rijen selecteren

Tot dusver heb je .loc gebruikt om kolommen te selecteren, waarbij je alle rijen steeds behield. Je kunt .loc ook gebruiken om bepaalde rijen te selecteren. Dit werkt exact hetzelfde als bij de kolommen, maar dan als eerste argument in .loc[], voor de komma.

Om bijvoorbeeld de eerste rij te selecteren, gebruik je df.loc[0, :]. In dit geval zijn de labels 0...n, maar let op dat de label niet hetzelfde is als de index bij bijvoorbeeld een Python lijst. In het volgende voorbeeld stel je de index in op de waarden van de kolom "Jaar".

df.set_index("Jaar", inplace=True)

      Station  Januari  Februari  ...  November  December  Jaargemiddelde
Jaar                              ...                                    
1901      260     -0.3      -0.9  ...       5.2       3.0             8.7
1902      260      4.7      -0.3  ...       3.7       0.8             8.2
1903      260      3.0       5.7  ...       5.6       0.9             9.2
1904      260      0.8       3.0  ...       5.5       4.0             8.9
1905      260      1.3       3.6  ...       3.8       2.4             8.7

Wil je nu de eerste rij selecteren - het eerste jaar dus -, dan gebruik je df.loc[1901, :]. Meerdere rijen selecteren werkt hetzelfde als bij meerdere kolommen selecteren. Je geeft een lijst op met de gewenste rijen, of een slice.

eerste_drie_jaren = df.loc[[1901, 1902, 1903], :]
eerste_drie_jaren = df.loc[1901:1903, :]

Filteren

Ook nu kun je weer een lijst met booleans gebruiken om de rijen te filteren. Stel dat je alleen de jaren wilt overhouden waar de gemiddelde temperatuur in januari hoger dan 0 graden was:

selector = df.loc[:, "Januari"] > 0
januari_boven_0 = df.loc[selector, :]

De lijst met booleans moet net zo lang zijn als het aantal rijen van de DataFrame. In de eerste stap selecteer je dus eerst de kolom "Januari" met df.loc[:, "Januari"]. Vervolgens gebruik je > 0 om voor elke rij te kijken of de waarde groter is dan nul. Per rij levert dit dus True of False op. Deze lijst met booleans voeg je in de tweede stap toe aan .loc[], op de plaats van de te selecteren rijen. Ook hier kun je het weer zien alsof je de lijst met booleans over de rij-labels heen schuift en alleen de rijen met True selecteert.

Alleen rijen

Overigens is het zo dat als je alle kolommen wilt behouden, je de : mag weglaten. Dit levert dus hetzelfde resultaat op:

eerste_drie_jaren = df.loc[1901:1903, :]
eerste_drie_jaren = df.loc[1901:1903]

Ofwel: gebruik je maar één argument in .loc[], dan maak je automatisch selecties van de rijen.

Rijen en kolommen filteren

Je hebt nu steeds op alleen de kolommen óf alleen de rijen gewerkt. Maar .loc[] staat uiteraard toe dat je tegelijkertijd kolommen en rijen selecteert. Bijvoorbeeld, alleen de gegevens van het eerste kwartaal voor de jaren 1980-1990:

q1_80 = df.loc[1980:1990, "Januari": "Maart"]

Of alleen het jaargemiddelde voor de jaren waar het jaargemiddelde boven de 10 graden lag:

boven_10 = df.loc[df.loc[:, "Jaargemiddelde"] > 10, "Jaargemiddelde"]

Overige methodes

Met .loc kom je een heel eind, maar er zijn ook andere methodes om gegevens te selecteren.

iloc

Net als .loc, kun je .iloc gebruiken om kolommen en/of rijen te selecteren. De werking is vrijwel hetzelfde, met het grote verschil dat je bij .iloc de integer gebaseerde positie gebruikt, in plaats van de labels. Je kunt .iloc vergelijken met het ophalen van items uit een lijst, waar je ook de integer gebaseerde index gebruikt. Net als bij een lijst, begin je bij .iloc ook met tellen bij 0.

Dus om de eerste drie jaren op te halen gebruik je .loc met labels, of .iloc met de integer gebaseerde index. (NB: je had de index op het jaartal gezet, weet je nog?)

    eerste_drie_jaren = df.loc[1901:1903]  # Let op: 1903 is inclusief
    eerste_drie_jaren = df.iloc[0:3]  # Let op: 3 is exclusief

Je ziet dat een groot - en eerlijk gezegd verwarrend - verschil is, dat bij .loc zowel de start- als eindpositie inclusief zijn. Bij .iloc is alleen de startpositie inclusief, de eindpositie is exclusief.

at en iat

Heb je de waarde uit een enkele cel nodig, dan kun je dat uiteraard met .loc of .iloc doen. Maar voor deze speciale situatie zijn ook .at en iat beschikbaar. Ze werken hetzelfde als .loc en .iloc, met het verschil dat je dus maar één rij en één kolom kunt opgeven. Dit zorgt ervoor dat het een iets snellere handeling is.

jan_2020 = df.at[2020, "Januari"]

Conclusie

Als je net met pandas begint, kan het selecteren van de juiste gegevens uit een DataFrame lastig zijn. De regels van .loc en aanverwanten zijn misschien niet helemaal intuïtief, bijvoorbeeld dat je .loc[] gebruikt in plaats van .loc(). Of dat bij een slice de eindwaarde óók inclusief is (maar bij .iloc dan weer niet).

Het is even wennen misschien. Daarom is het wel aan te raden om er goed mee te oefenen, want het zal zelden zijn dat je de hele DataFrame nodig hebt.

Alle code voorbeelden en voorbeeldbestanden van dit project zijn ook op Github te bekijken.

In pandas werk je vaak met gegevens in een DataFrame (of een Series), maar je gegevens komen vaak ergens anders vandaan. In deze tutorial leer je hoe je gegevens inleest vanuit CSV, Excel en JSON. Ook leer je hoe je een DataFrame weer opslaat in één van deze formaten.

Voordat je begint

Maak een nieuw project aan, met een nieuwe virtual environment. Installeer daarin ook pandas.

cd projects
mkdir pandas_gegevens && cd pandas_gegevens
python -m venv .venv
source .venv/bin/activate  # .venv\Scripts\activate.bat voor Windows
python -m pip install pandas
python -m pip freeze > requirements.txt

Alle code voorbeelden en voorbeeldbestanden van dit project zijn ook op Github te bekijken.

Series en DataFrames

Veelal zul je in pandas met Series en DataFrames werken. Maar wat is een DataFrame precies? Je kunt een DataFrame het best vergelijken met een tabel zoals je die ziet als je een spreadsheet opent (bijvoorbeeld in Excel). Je hebt dus rijen en kolommen.

De donkergrijze rij bevat de kolomnamen en de donkergrijze eerste kolom bevat de index (rijnummers of namen).

Series

Omdat een kolom van het type Series is, is het handig om hiermee te beginnen. Een Series is een 1-dimensionale lijst die elk type data kan bevatten, bijvoorbeeld int, str of date. Voor beginners is het soms verwarrend, maar een Series heeft ook een index, ofwel labels.

De donkergrijze blokken zijn samen de index, terwijl de lichtgrijze blokken de gegevens bevatten. Dus een Series is 1-dimensionaal (het is één lijst met gegevens), maar elk gegeven heeft wel een index. Maak je een Series aan zonder de index te specificeren, dan loopt de index simpelweg van 0 tot n.

Om een Series te maken, plaats je in main.py bovenin de import import pandas as pd. Deze manier van pandas importeren is een gewoonte die is ontstaan en die je overal zult zien. Het is dus handig jezelf dit ook aan te leren.

Vervolgens kun je een eenvoudige Series maken zonder index op te geven. Plaats hiervoor een lijst met gegevens in pd.Series().

import pandas as pd

# Maak een Series aan zonder index
s = pd.Series(["aap", "noot", "mies"])
print(s)

0     aap
1    noot
2    mies
dtype: object

Je ziet dat de index nu loopt van 0 t/m 2. Verder zie je dtype: object. Dit is kort voor datatype. In dit geval is het type "object", wat elk Python-object kan omvatten, inclusief str. Standaard slaat pandas tekst op als "object". Dit kan voor fouten zorgen, want een object kan ook iets anders zijn, en je kunt dus per ongeluk verschillende objecten in je Series plaatsen.

Om dit te voorkomen kun je opgeven dat je string of pd.StringDtype() als dtype wilt:

# Maak een Series aan zonder index, met type `str`
s = pd.Series(["aap", "noot", "mies"], dtype="string")
# s = pd.Series(["aap", "noot", "mies"], dtype=pd.StringDtype())
print(s)

0     aap
1    noot
2    mies
dtype: string

Je ziet dat dtype nu wel "string" is.

Je kunt ook een eigen index meegeven:

# Maak een Series aan met index
s = pd.Series(["aap", "noot", "mies"], index=["a", "b", "c"], dtype="string")
print(s)

a     aap
b    noot
c    mies
dtype: string

En nu kun je de waarde op index "a" ophalen:

# Haal waarde op index 'a' op
aap = s["a"]
print(aap)  # aap

Tot slot kun je ook een Series aanmaken op basis van een dict, waarbij de keys de index zullen vormen. Vergeet dan niet de dtype achteraf nog in te stellen op "string".

# Maak een Serie op basis van een `dict`
d = {
    "a": "aap",
    "b": "noot",
    "c": "mies"
}

s = pd.Series(d).astype("string")  # Stel de dtype in op "string"
print(s)

a     aap
b    noot
c    mies
dtype: string

DataFrame

Een DataFrame is feitelijk een combinatie van meerdere Series, waarbij de index van de Series vervalt en de DataFrame als geheel een index krijgt.

# Maak een DataFrame op basis van een `dict` van `Series`.
data = {
    "kolom1": s,  # s is de eerder aangemaakte Serie
    "kolom2": s,  # s is de eerder aangemaakte Serie
}
df = pd.DataFrame(data)
print(df.head())

    kolom1 kolom2
a    aap    aap
b   noot   noot
c   mies   mies

Met df.head() toon je de eerste 5 rijen van een DataFrame. Je ziet dat de keys van de dict de kolomnamen zijn geworden. De index is ingesteld op "a", "b" en "c", omdat beide Series dit ook hadden. Kan pandas geen goede index bepalen, dan zal het simpelweg 0, 1, 2 worden.

Je kunt een DataFrame ook maken op basis van een dict met lijsten. Stel ook de index in.

# Maak een DataFrame op basis van een `dict` van lijsten
data = {
    "kolom1": [1, 2, 3],
    "kolom2": [4, 5, 6]
}
df = pd.DataFrame(data, index=["rij1", "rij2", "rij3"])
print(df.head())

        kolom1  kolom2
rij1       1       4
rij2       2       5
rij3       3       6

Je kunt nu een enkele kolom ophalen op basis van de kolomnaam:

# Haal een kolom op op basis van label
kolom1 = df["kolom1"]
print(kolom1)

rij1    1
rij2    2
rij3    3
Name: kolom1, dtype: int64

Met .loc[] haal je een rij op, op basis van de index.

# Haal een rij op op basis van index
rij_2 = df.loc["rij2"]
print(rij_2)
print(type(rij_2))

kolom1    2
kolom2    5
Name: rij2, dtype: int64
<class 'pandas.core.series.Series'>

Je ziet dat ook een rij een Series is, en dat de kolomnamen de index van de Series zijn geworden.

Verder lezen

Je hebt nu een basisbegrip van Series en DataFrames. Er valt nog veel meer over te vertellen, bijvoorbeeld hoe je meerdere kolommen en rijen kunt selecteren en hoe je gegevens verwijdert, toevoegt en wijzigt. Wil je meer lezen, bekijk dan de introductie op data structuren in de documentatie van pandas. Ook de documentatie over indexing is interessant.

Omdat de documentatie van pandas soms overweldigend kan zijn, zullen we in de toekomst ook aparte tutorials wijden aan het werken met Series en DataFrames, en dan met name het selecteren van gegevens.

CSV

Een CSV-bestand (Comma Separated Values) is een veelgebruikt bestandsformaat voor het uitwisselen van gegevens tussen verschillende applicaties. Het is een eenvoudig tekstbestand waarin elke regel een gegevensrecord voorstelt en de waarden in elk record door komma's (of puntkomma's) van elkaar gescheiden zijn. CSV-bestanden zijn populair omdat ze eenvoudig te openen en bewerken zijn in een teksteditor en omdat je er eenvoudig mee kunt werken in allerlei programma's en programmeertalen.

Opslaan als CSV

Maak nogmaals een eenvoudige Dataframe aan:

# Maak een DataFrame op basis van een `dict` van lijsten
data = {
    "kolom1": [1, 2, 3],
    "kolom2": [4, 5, 6]
}
df = pd.DataFrame(data, index=["rij1", "rij2", "rij3"])
print(df.head())

Deze Dataframe sla je nu eenvoudig op naar een CSV-bestand. Je gebruikt hiervoor de methode to_csv. Dit is een instance-methode, dus je roept het aan vanaf je net aangemaakte Dataframe: df.to_csv().

Er zijn veel opties beschikbaar voor to_csv. In de meeste gevallen heb je er maar enkele nodig. De belangrijkste is natuurlijk het eerste argument: het pad naar een CSV-bestand. Verder zijn sep en index nog interessant. Met sep geef je aan wat het scheidingsteken moet zijn. Standaard is dit een komma (,), maar zelf geef ik altijd de voorkeur aan ;. Ook kies ik er meestal voor de index niet weg te schrijven in het CSV-bestand, zodat je een schoon bestand overhoudt met enkel de kolomnamen en de gegevens. Het geheel ziet er dan zo uit:

# Schrijf de DataFrame naar een CSV-bestand
df.to_csv("df1.csv", sep=";", index=False)

En zo eenvoudig is het: je hebt een CSV-bestand genaamd df1.csv opgeslagen! Voor alle opties van to_csv lees je de documentatie. Overigens kun je to_csv ook op een Series aanroepen.

CSV inlezen

Andersom - dus het inlezen van een CSV-bestand naar een DataFrame - werkt net zo eenvoudig. Je gebruikt hiervoor read_csv. Deze roep je aan vanaf pd (pandas). Ook hier geef je weer een bestandsnaam op en eventueel het scheidingsteken (als dat geen komma is).

# Lees een CSV-bestand in naar een DataFrame
df1 = pd.read_csv("df1.csv", sep=";")
print(df1.head())

Ook hier zijn weer veel extra opties mogelijk die helpen bij het goed inlezen van de data. Een paar verdienen extra aandacht.

Datum

Met parse_dates en date_format kun je aangeven welke kolommen een datum bevatten, en in welk formaat. Stel dat je een CSV-bestand genaamd datums.csv hebt met de volgende inhoud:

Datum;Aantal
2024-01-01;4
2024-01-02;6
2024-01-03;3
2024-01-04;8
2024-01-05;10

Met parse_dates en date_format kun je nu aangeven hoe pandas de kolom Datum moet inlezen.

# Lees een CSV-bestand in met een datum kolom
df_datums = pd.read_csv("datums.csv", sep=";", parse_dates=["Datum"], date_format="%Y-%m-%d")
print(df_datums.dtypes)

Datum     datetime64[ns]
Aantal             int64
dtype: object

Je ziet dat Datum nu een dtype van datetime65[ns] heeft, wat wil zeggen dat het niet meer een tekst is, maar echt een datum-formaat. Dit maakt het mogelijk om er allerlei datumafhankelijke bewerkingen mee te doen, zoals het groeperen op maand, of eenvoudig selecteren van alle vrijdagen om maar iets te noemen.

Zie de documentatie van strftime om te leren hoe de datumnotatie werkt.

Missende waarden

Een ander handigheidje is dat je kunt bepalen hoe er met missende waarden omgegaan moet worden. Standaard worden al heel wat teksten herkend als missende waarden, namelijk:

['-1.#IND', '1.#QNAN', '1.#IND', '-1.#QNAN', '#N/A N/A', '#N/A', 'N/A', 'n/a', 'NA', '<NA>', '#NA', 'NULL', 'null', 'NaN', '-NaN', 'nan', '-nan', 'None', '']

Maar heb je zelf ook waarden die als missend herkend moeten woorden, bijvoorbeeld ?, dan kan dat met na_values. Neem bijvoorbeeld het CSV-bestand missend.csv met de volgende inhoud:

kolom1;kolom2
1;4
2;?
3;6

Regel 2, kolom 2 bevat een vraagteken wat pandas moet herkennen als missende waarde.

# Lees een CSV-bestand met missende waarden in
df_missend = pd.read_csv("missend.csv", sep=";", na_values="?")
print(df_missend.head())

      kolom1  kolom2
0       1     4.0
1       2     NaN
2       3     6.0

Je ziet dat op regel 2, kolom 2 nu geen vraagteken meer bevat, maar NaN, waarmee pandas aangeeft dat het een missende waarde is (Not a Number).

Er zijn nog veel meer mogelijkheden met read_csv, veel heb je alleen in uitzonderlijke gevallen nodig. Bekijk de volledige documentatie om meer te leren.

Excel

Je hebt leren werken met CSV-bestanden, een formaat dat je veel tegenkomt om gegevens uit te wisselen. Een ander veel voorkomend formaat is Excel. Ook hier kan pandas goed mee omgaan, en eigenlijk werkt het vrijwel hetzelfde als werken met CSV. In plaats van to_csv heb je to_excel en in plaats van read_csv heb je read_excel. De opties zijn grotendeels hetzelfde.

Er is echter één belangrijk verschil: voor het werken met Excel heb je nog een andere package nodig die het daadwerkelijk lezen/schrijven doet. Er zijn enkele pakketen beschikbaar:

Pakket Formaat openpyxl .xlsx xlrd .xls pyxlsb .xlsb calamine alle

Installeer één van deze pakketten in je venv, zodat pandas ermee kan werken. Je hoeft verder niets te importeren, dat handelt pandas voor je af.

Een belangrijk verschil tussen CSV en Excel is dat je in een Excel-bestand meerdere werkbladen (sheets) kunt hebben. Met de parameter sheet_name kun je aangeven welke sheet(s) je wilt inlezen. Standaard staat dit op 0, het eerste werkblad. Je kunt de index gebruiken, of de naam van een werkblad. Je kunt ook een lijst met meerdere werkbladen opgeven. Het resultaat is dan een dict met de namen als sleutel en de DataFrames als waarde.

Een kort voorbeeld. Installeer eerst openpyxl:

python -m pip install openpyxl

Vervolgens kun je het tweede werkblad van een Excel-bestand genaamd excel.xlxs inlezen.

# Lees het tweede werkblad van een Excel-bestand in
df_excel = pd.read_excel("excel.xlsx", sheet_name=1)
print(df_excel.head())

    7   10
0   8  11
1   9  12

Om een DataFrame naar Excel te schrijven, gebruik je to_excel, wat vrijwel hetzelfde werkt als to_csv. Ook hiervoor heb je een extra package nodig. Je kunt hiervoor xlsxwriter of openpyxl gebruiken.

Lees de documentatie om meer te leren over het werken met Excel.

JSON

Ook het werken met JSON is redelijk vergelijkbaar als met CSV-bestanden en Excel-bestanden. Maar daar waar CSV en Excel erg lijken op een DataFrame (rijen en kolommen), is dit bij JSON niet het geval.

Een extra optie bij to_json en read_json is dan ook orient, waarmee je bepaalt hoe de vertaalslag van rijen/kolommen naar of van een meer dict-achtige structuur gemaakt moet worden. De standaard bij DataFrames is columns.

Stel je hebt het volgende JSON-object, opgeslagen in json-bestand.json:

{
  "kolom1": {
    "rij1": 1,
    "rij2": 2,
    "rij3": 3
  },
  "kolom2": {
    "rij1": 4,
    "rij2": 5,
    "rij3": 6
  }
}

De volgende code leest het bestand in en zet het om naar een DataFrame:

# Lees een JSON bestand in
df_json = pd.read_json("json-bestand.json")
print(df_json.head())

Het resultaat is dan dat de eerste sleutels ("kolom1", "kolom2") de kolom-koppen worden. De tweede-niveau sleutels ("rij1", "rij2", "rij3") vormen de index.

        kolom1  kolom2
rij1       1       4
rij2       2       5
rij3       3       6

Zie de documentatie om meer te leren over de verschillende oriëntatiemogelijkheden.

Andere bestanden

Naast het werken met CSV, Excel en JSON zijn er nog tal van andere mogelijkheden om gegevens naar op te slaan of vanuit te openen. Een aantal voorbeelden zijn HTML, XML, Parquet en SQL. Zie de documentatie voor een volledige lijst en alle mogelijkheden.

Conclusie

Gegevens kunnen overal vandaan komen en veel verschillende formaten hebben. In pandas zul je echter meestal met een DataFrame of een Series werken. Gelukkig heeft pandas vele methoden om eenvoudig gegevens in te lezen of juist weg te schrijven naar bijvoorbeeld CSV, Excel en JSON.

Alle methodes werken ongeveer hetzelfde. Gebruik to_* om naar een bepaald formaat te schrijven en gebruik read_* om vanuit een bepaald formaat in te lezen. Voor de details kun je altijd de documentatie erbij pakken!

• User guide

• API referentie

Succes!

Alle code voorbeelden en voorbeeldbestanden van dit project zijn ook op Github te bekijken.

In deze tutorial leer je daarom werken met de OpenAI API. Een API is een manier om vanuit je eigen programma te communiceren met een ander programma, vaak via het internet. Je kunt op deze manier de AI-modellen van OpenAI gebruiken zonder naar hun website te gaan.

Het project

In dit project maak je een script dat jou toetst over een bepaald onderwerp. Je geeft een Wikipedia-URL op en met behulp van AI maak je hier automatisch een samenvatting van én maak je drie vragen waarmee je kennis over het gegeven onderwerp kunt toetsen. Uiteraard krijg je ook de correcte antwoorden!

Let op: om te kunnen werken met de API van OpenAI heb je een account nodig. In tegenstelling tot ChatGPT is het gebruik van de API niet gratis, je betaalt naar gebruik. Zie deze pagina voor meer informatie over de kosten. Het kost je niet veel, zeker niet bij kleinere projecten zoals deze. Bovendien kun je een bovengrens instellen, zodat je nooit tegen onverwachte kosten aanloopt.

Maak nu eerst een account als je die nog niet hebt. Nadat je alles hebt ingesteld, kun je een apart project in de OpenAI Dashboard aanmaken. Klik eerst linksbovenin op je (organisatie)naam en vervolgens op "Create project". Maak een nieuw project aan met de naam "WikiTest".

Vervolgens maak je een API-key aan voor het project. Ga naar de API keys pagina en klik op "Create new secret key". Geef het een naam, kies het zojuist aangemaakte project en klik op "Create secret key". LET OP: kopieer de API-key direct en sla het op een veilige plek op, je krijgt het niet nogmaals te zien.

Als je een account en een API-key hebt aangemaakt, maak je een nieuw Python project aan en installeer je de drie externe packages die je gaat gebruiken: openai, wikipedia-api en python-dotenv. De openai package is de client om met de API van OpenAI te communiceren. De wikipedia-api package is een handig hulpmiddel om pagina's van Wikipedia op basis van een titel op te halen en de tekst in te lezen. Het is een client om te communiceren met de Wikipedia API. De python-dotenv package tot slot is een hulpmiddel om op een veilige manier je API-key in te kunnen lezen, waarover later meer.

cd projects
mkdir wikitest && cd wikitest
python -m venv .venv
source .venv/bin/activate  # .venv\Scripts\activate.bat voor Windows
python -m pip install openai wikipedia-api python-dotenv
python -m pip freeze > requirements.txt

Je kunt de code van dit project ook op Github bekijken.

API-key

Je API-key is persoonlijk, als deze in de verkeerde handen valt kan iemand het gebruiken en draai jij voor de kosten op. Het is daarom belangrijk om deze geheim te houden. Hier zijn verschillende manieren voor. In dit project gebruik je python-dotenv. Je maakt een .env bestand in je project aan, waarin je de API-key noteert.

OPENAI_API_KEY=sk-proj-123abc

Noem je API-key OPENAI_API_KEY en de openai client zal het automatisch inlezen. Zie ook de documentatie van OpenAI.

Maak ook een .gitignore-bestand aan, waarin je aangeeft dat het .env bestand niet in je repository opgenomen mag worden.

.env
.venv
*.pyc
__pycache__

Ook al gebruik je nu (nog) geen Git, het is toch verstandig alvast wel een .gitignore aan te maken. Ben je wel zover om versiebeheer te gaan doen met Git en je pusht je code naar bijvoorbeeld Github, dan zal je API-key niet per ongeluk meegestuurd worden.

Wikipedia pagina inlezen

Om een samenvatting van en toetsvragen over een Wikipedia-pagina te maken, moet je de pagina wel kunnen laten lezen door het AI-model. Er zijn hiervoor verschillende manieren, maar om het zo platform-onafhankelijk te houden, lees je eerst de pagina zelf in als platte tekst. Deze tekst kun je dan weer naar het model sturen.

Wikipedia heeft gelukkig een API zodat de pagina eenvoudig programmatisch is in te lezen. En met de package wikipedia-api wordt dit proces nog eenvoudiger.

Maak in je project een bestand wiki.py aan en plaats hierin de volgende code.

import wikipediaapi

USER_AGENT = "WikiTest (info@python-cursus.nl)"
LANGUAGE = "nl"


def read_wiki(titel):
    """Lees een Wikipedia-artikel in."""

    # Initialiseer de Wikipedia client
    wiki = wikipediaapi.Wikipedia(
        user_agent=USER_AGENT,
        language=LANGUAGE,
        extract_format=wikipediaapi.ExtractFormat.WIKI
    )

    # Haal de pagina op, op basis van titel
    page = wiki.page(titel)

    # Controleer of de pagina bestaat
    if not page.exists():
        raise ValueError("Pagina bestaat niet")

    # Geef de tekst terug
    return page.text

Met deze functie kun je een Wikipedia-pagina inlezen op basis van een op te geven titel. Zorg ervoor dat je de USER_AGENT aanpast naar je eigen gegevens.

Zie de documentatie van Wikipedia API voor meer over het gebruik van de package.

Samenvatting en toets maken

Nu je een Wikipedia-pagina in kunt lezen, is de volgende stap het maken van een samenvatting en toetsvragen over de tekst. Hiervoor gebruik je een AI-model, in dit voorbeeld via de API van OpenAI. In de kern is het werken met de API van OpenAI eenvoudig. De aanroep ziet er als volgt uit:

client = OpenAI()
response = client.chat.completions.create(
    model=MODEL,  # Bijvoorbeeld 'gpt-4o'
    response_format={"type": "json_object"},
    messages=[system_message, user_message]
)

Je roept de completions-endpoint aan, met het gekozen model, de bericht(en) die je wilt sturen en optioneel een formaat waarin het antwoord teruggegeven moet worden.

Er zijn nog meer opties beschikbaar, maar voor nu volstaat dit. Zie de documentatie voor meer informatie.

De berichten (messages) bestaan uit een lijst met één of meer berichten. Een bericht bestaat uit een dict met de sleutels role en content. De rollen zijn onder ander system, user en assistant. De berichten zijn de berichten die je ook in ChatGPT zou zien, dus jouw berichten en de reactie van het model (assistant). Het verschil hier is dat je ook de reactie van het model op kunt sturen. Dit kan nodig zijn als je een applicatie maakt waarbij je de geschiedenis van het gesprek wilt behouden.

De messages voor dit project kun je als volgt opstellen:

    # Bereid de instructies voor
    # Zorg ervoor dat het model JSON teruggeeft
    system_message = {
        "role": "system",
        "content": """
            Je bent een assistent die Wikipediapagina's samenvat en vragen bedenkt voor
            studenten om hun kennis te toetsen. Je reageert altijd in JSON.
            """
    }

    # Zorg ook voor een voorbeeld van hoe de JSON eruit moet zien.
    # Er zijn geen garanties dat het model zich hier aan houdt, maar
    # in de praktijk gaat het 99% van de tijd wel goed.
    user_prompt = """
        Lees de tekst die hierna volgt\n.
        Maak een samenvatting van de tekst in maximaal drie zinnen\n.
        Maak drie meerkeuzevragen met opties A, B en C over het onderwerp.
        Er kan steeds 1 antwoord goed zijn\n.
        Geef van elke vraag aan wat het goede antwoord is (A, B of C)\n.
        Gebruik het volgende JSON-schema: \n\n

        {
            "samenvatting": "De samenvatting",
            "vragen: [
                {
                    "vraag": "De eerste vraag",
                    "opties: ["A: Optie A", "B: Optie B", "C: Optie C"],
                    "antwoord": A
                },
                {
                    "vraag": "De tweede vraag",
                    "opties: ["A: Optie A", "B: Optie B", "C: Optie C"],
                    "antwoord": B
                },
            ]
        }

        De tekst is als volgt:\n\n
        """

    user_message = {
        "role": "user",
        "content": user_prompt + text
    }

Hierbij is text op het de een-na-laatste regel de ingelezen Wikipediapagina.

Het is erg belangrijk om in je prompt aan te geven dat je JSON als output wilt, ook al heb je dit eerder al aangegeven bij het aanroepen van de API. In dit geval is dat in de system prompt gedaan. Zie de JSON mode documentatie voor meer toelichting hierop.

Het is ook belangrijk om een voorbeeld te geven van de gewenste JSON-structuur. Zo weet het model beter wat het terug moet geven. Doe je dit niet, dan is de kans groter dat bijvoorbeeld de sleutels ("vraag", "opties", "antwoord", etc.) soms een andere naam krijgen (bijvoorbeeld "antwoordopties" in plaats van "opties"). Omdat je later met de sleutels wilt werken, wil je wel dat dit consistent is.

Werken met Large Language Models blijft fundamenteel onzeker. Door het opgeven van voorbeelden haal je veel van de onzekerheid weg, maar het is niet gegarandeerd dat de gewenste JSON-structuur elke keer wordt teruggegeven. Houd hier rekening mee in de rest van je code.

Plaats bovenstaande nu in een functie create_text, in een bestand toets.py.

def create_test(text):
    """
    Gebruik OpenAI om de opgegeven tekst samen te vatten en er een toets over te maken.
    """
    client = OpenAI()

    # Bereid de instructies voor
    # Zorg ervoor dat het model JSON teruggeeft
    # ...

    # Haal de response op
    # ...

    return response.choices[0].message.content

Bekijk de complete code op Github

De toets afnemen

Je hebt nu de code om een Wikpedia-pagina in te lezen en de code om hiervan met behulp van AI een samenvatting en een toets van te maken. De laatste stap is het daadwerkelijk afnemen van de toets. Voor dit voorbeeld kun je het eenvoudig houden door de input-functie te gebruiken. Uiteraard zou je het uitgebreider kunnen maken door er bijvoorbeeld een webapplicatie van te maken.

Maak hiervoor een functie take_test in het bestand toets.py. In vereenvoudigde vorm ziet het eerste deel van deze functie er als volgt uit:

def take_test():
    print("Geef de titel op (haal dit uit de url, na '/wiki/'")
    titel = input("Titel: ")

    # Lees de Wikipedia-pagina in
    text = read_wiki(titel=titel)

    # Maak de samenvatting en toets
    result = create_test(text=text)

    # Zet om van JSON naar dict
    result_json = json.loads(result)
    samenvatting = result_json.get("samenvatting")
    vragen = result_json.get("vragen")

In een volledige versie gebruik je try/except-blokken om eventuele fouten af te handelen.

Het laatste deel van de functie:

def take_test():
    # ...

    # Toon samenvatting
    print("\nSAMENVATTING")
    print(samenvatting)

    # Begin de toets. Elke vraag bestaat uit een `dict` met vraag,
    # opties en correct antwoord.
    print("TOETS")
    for vraag in vragen:
        print(f"Vraag: {vraag['vraag']}\n")
        for optie in vraag["opties"]:
            print(optie)

        user_antwoord = input("Wat is je antwoord (A, B of C)? ")
        if user_antwoord.upper() == vraag["antwoord"]:
            print("Goed!\n")
        else:
            print(f"Helaas, het goede antwoord is {vraag['antwoord']}\n")

Toon eerst de samenvatting. Vervolgens itereer je over alle vragen en de antwoordopties en controleer je of de gebruiker hetzelfde antwoord geeft als het goede antwoord.

Bekijk de complete code op Github

Nu rest alleen nog de code aan te roepen in main.py:

from dotenv import load_dotenv
from toets import take_test

if __name__ == '__main__':
    load_dotenv()
    take_test()

Gebruik load_dotenv() om je .env bestand met je API-sleutel van OpenAI in te lezen. Vervolgens roep je take_test() aan en ben je klaar om je code uit te proberen!

python main.py

Over welke Wikipediapagina wil je een toets maken?
Geef de titel op (haal dit uit de url, na '/wiki/'
Titel: Guido_van_Rossum

SAMENVATTING
Guido van Rossum is een Nederlandse informaticus, bekend als de ontwerper van de programmeertaal Python. Hij ontving in 1999 de Dr. Dobb's
Journal Excellence in Programming Award en diverse andere accolades voor zijn bijdragen aan de softwareontwikkeling.
Van Rossum woonde in Nederland en sinds 1995 in de VS, en werkte voor bedrijven zoals Google, Dropbox en Microsoft.

TOETS
Vraag: In welk jaar ontwierp Guido van Rossum de programmeertaal Python?

A: 1980
B: 1989
C: 1999
Wat is je antwoord (A, B of C)? b
Goed!

// etc

Conclusie

In deze tutorial heb je een eenvoudig programma gemaakt dat een Wikipedia-pagina inleest en er vervolgens met behulp van de OpenAI API een samenvatting van maakt en er een toets over maakt. Het is een eenvoudig voorbeeld om te laten zien dat je ook op andere manieren AI-modellen kunt gebruiken dan via een chat-interface.

Het voordeel is dat je hiermee bepaalde taken kunt automatiseren, dus niet steeds weer je opdrachten in een chat typen! Een ander voordeel is dat je eenvoudig je eigen input mee kunt geven, zoals documenten of inhoud uit spreadsheets. Vervolgens kun je de response weer programmatisch verwerken.

Dit voorbeeld was met OpenAI, maar bekijk ook eens de API's van andere aanbieders. Veelal hebben ze zelf ook een Python-client en is de werking vrijwel hetzelfde als die van OpenAI. Enkele voorbeelden:

• Mistral

• Claude

• Google

• Microsoft

De mogelijkheden zijn eindeloos. Veel succes!

Als je met een API werkt, zullen de gegevens heel vaak in JSON worden opgestuurd. Bijna altijd zul je ook de structuur weten van de JSON, of je het nu ontvangt of opstuurt. En ook bijna altijd zul je als je werkt met JSON Python-objecten naar JSON willen omzetten, of juist van JSON naar Python-objecten. Van Python naar JSON noem je serialiseren. Van JSON naar Python noem je deserialiseren.

Als je serialiseert of deserialiseert is het prettig als je weet dat de gegevens voldoen aan jouw verwachting. Stel je verwacht van een API de volgende structuur:

[
   {
      "Naam":"JSON",
      "Type":"Gegevensuitwisselingsformaat",
      "isProgrammeertaal":false
   },
   {
      "Naam":"JavaScript",
      "Type":"Programmeertaal",
      "isProgrammeertaal":true
   }
]

Zet je dit om naar Python, dan wil je valideren dat alle gegevens aanwezig zijn, bijvoorbeeld. Of dat extra gegevens die eventueel meekomen niet in je Python-object terechtkomen. Andersom, als je een Python-object hebt dat je naar een API wilt sturen als JSON, dan is het prettig als je er zeker van kunt zijn dat alle verplichte velden aanwezig zijn en van het juiste gegevenstype zijn.

In deze tutorial leer je daarom werken met Pydantic. In hun eigen woorden:

Pydantic is the most widely used data validation library for Python.

Pydantic is een bibliotheek voor het valideren en serialiseren van Python-objecten. Om dit te bereiken maak je gebruik van de ingebouwde type hints van Python. Een voorbeeld zal duidelijk maken hoe het werkt.

from pydantic import BaseModel

# Maak een klasse die overerft van Pydantics BaseModel
class User(BaseModel):
    naam: str  # Naam is verplicht en altijd een str
    leeftijd: int  # Leeftijd is verplicht en altijd een int

# User gegevens in een `dict` 
user_dict = {
    "naam": "Guido",
    "leeftijd": 42
}

# Maak een user object aan door de dict uit te pakken
user = User(**user_dict)
print(user)
# Output: User(naam='Guido', leeftijd=42)

# Je kunt nu attributen aanroepen
print(user.naam)  # Guido

# Je kunt een object ook met argumenten aanmaken
user = User(naam="Guido", leeftijd=42)

# Of met model_validate()
user = User.model_validate(user_dict)

# Alle velden zijn verplicht, ontbreekt er één, dan krijg je een ValidationError
user_faux = User(naam="Guido")
# ...
# leeftijd
#   Field required [type=missing, input_value={'naam': 'Guido'}, input_type=dict]


# Of als je een verkeerd type gebruikt
user_faux = User(naam="Guido", leeftijd="vijftig")
# ...
# leeftijd
#   Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='vijftig', input_type=str]

# Zet om in JSON
user_json = user.model_dump_json()
print(user_json)
# Output: {"naam":"Guido","leeftijd":42}

Je ziet, je kunt Pydantic gebruiken om eenvoudig klassen te maken zodat je altijd zeker weet dat je met de juiste gegevens werkt.

Het project

Gebruik hetzelfde project als in Werken met JSON. In plaats van de gegevens op te slaan als JSON en te verwerken, ga je ze met Pydantic valideren en verwerken. Het resultaat blijft hetzelfde, namelijk per jaar het totale bevolkingsaantal van Nederland:

1950: 10.026.773
1951: 10.200.280
...
2022: 17.590.672
2023: 17.811.291

Voordat je begint

Ga naar het project, activeer de virtual environment en installeer Pydantic:

cd projects/cbs_json
source .venv/bin/activate  # .venv\Scripts\activate.bat voor Windows
python -m pip install pydantic
python -m pip freeze > requirements.txt

JSON-gegevens ophalen en valideren

In main.py zijn twee functies aanwezig: get_data en get_total_population. De eerste wijziging maak je in get_data. Met deze functie haal je de JSON-gegevens op van het CBS. De wijziging die je maakt is dat je valideert of de inkomende data voldoet aan wat je verwacht, en je gooit direct weg wat je niet nodig hebt.

De JSON die je terugkrijgt, ziet er ongeveer zo uit (sterk ingekort):

{
  "odata.metadata": "https://opendata.cbs.nl/ODataApi/OData/85496NED/$metadata#Cbs.OData.WebAPI.TypedDataSet", 
  "value": [{"ID": 0, "Perioden": "1950JJ00", "TotaleBevolking_1": 10026773, "Mannen_2": 4998251}]
}

Je bent alleen geïnteresseerd in de waardes in value. Deze waarden staan in een lijst, dus je Response-model kan heel eenvoudig zijn. Maak de volgende klasse aan:

from pydantic import BaseModel
# ...

class Response(BaseModel):
    value: list

# ...

In get_data schreef je de JSON naar een bestand. Dat vervang je nu door een versie waarin je Pydantic gebruikt.

Oude versie main.py

# ...

def get_data():
    session = requests_cache.CachedSession(expire_after=tonight)
    response = session.get(URL)

    # Als de HTTP-code 400 of hoger is, zal er een uitzondering worden opgeworpen
    response.raise_for_status()
    data = response.json()

    # Sla bestand op
    with open("data.json", "w") as f:
        json.dump(data, f, indent=2)

    return data

Nieuwe versie main.py

from pydantic import BaseModel, ValidationError

# ...

class Response(BaseModel):
    value: list


def get_data():
    session = requests_cache.CachedSession(expire_after=tonight)
    response = session.get(URL)

    # Als de HTTP-code 400 of hoger is, zal er een uitzondering worden opgeworpen
    response.raise_for_status()

    # Valideer de inkomende JSON, behoud alleen de `values`
    try:
        validated_response = Response.model_validate_json(response.content)
    except ValidationError as e:
        print(e)
        return

    return validated_response

Met Response.model_validate_json(response.content) zet je de inkomende JSON om naar het Response-object, en je valideert dit direct. Alle velden die niet in Response zijn gedefineerd, worden genegeerd. Je houdt zo dus enkel de lijst value over.

Print je response.value, dan zie je iets als:

print(validated_response.value)
# [{'ID': 0, 'Perioden': '1950JJ00', 'TotaleBevolking_1': 10026773, 'Mannen_2': 4998251, ....

Mocht er nu iets niet goed gaan en de data is niet valide, dan werpt Pydantic een ValidationError op. Is dat het geval, geef dan None terug. Anders geef je de validated_response terug.

Gegevens verwerken

Ook de functie get_total_population kun je wijzigen om met Pydantic te werken. Uit alle data ben je alleen geïnteresseerd in het jaartal en de totale bevolking. Maak een tweede Pydantic-model aan:

# ...

class Data(BaseModel):
    jaar: str
    totale_bevolking: int


# ...

Het jaartal is een str en de totale bevolking een int.

Wijzig ook de get_total_population-functie.

Oude versie main.py

# ...

def get_total_population():
    # Open het bestand
    with open("data.json") as f:
        data = json.load(f)  # data is nu een Python object (dict)

    # Bereid een lege lijst voor
    result = []

    # Loop door de rijen in de data
    for row in data["value"]:
        year = row["Perioden"].split("JJ00")[0]  # Schoon het jaartal op
        value = row["TotaleBevolking_1"]

        # Voeg het jaartal en de waarde toe aan de lijst als een tuple
        result.append((year, value))

    return result

Nieuwe versie main.py

# ...

def get_total_population(validated_response):
    # Bereid een lege lijst voor
    result = []

    # Loop door de rijen in de data
    for row in validated_response.value:
        jaar = row["Perioden"].split("JJ00")[0]  # Schoon het jaartal op
        totale_bevolking = row["TotaleBevolking_1"]

        try:
            data = Data(jaar=jaar, totale_bevolking=totale_bevolking)
        except ValidationError:
            print("Geen geldige data, sla rij over")
            continue

        # Voeg het jaartal en de waarde toe aan de lijst als een Data instantie
        result.append(data)

    return result

Omdat je nu geen JSON uit een bestand meer inleest, zorg je ervoor dat de functie een parameter validated_response ontvangt. Verder itereer je nu over validated_data.value - Dus het veld value van het Response-model. En tot slot valideer je de data (jaar en bevolking) met het Pydantic-model Data dat je zojuist hebt aangemaakt.

Samenvoegen

Alles is nu klaar. Je kunt nu met get_data de data ophalen en valideren. Is er geldige data, dan ga je verder met get_total_population. Tot slot itereer je over elk item in het resultaat, wat een lijst met Data-objecten is. Dit was eerst een tuple met jaar-bevolking paren. Doordat het nu Data-objecten zijn kun je de velden (attributen) aanroepen, wat het geheel explicieter en dus duidelijker maakt.

Oude versie main.py

# ...

if __name__ == "__main__":
    data = get_data()
    total_population = get_total_population()

    for year, value in total_population:
        print(f"{year}: {value:n}")

Nieuwe versie main.py

# ...

if __name__ == "__main__":
    validated_response = get_data()
    if validated_response:
        total_population = get_total_population(validated_response=validated_response)

        for row in total_population:
            print(f"{row.jaar}: {row.totale_bevolking:n}")

Et voila, hetzelfde resultaat als eerst, maar nu gevalideerd met Pydantic én handiger om mee te werken omdat je met de namen van attributen kunt werken.

Conclusie

In deze tutorial heb je de basis geleerd van het werken met Pydantic. Er is nog veel meer mogelijk, maar in de kern gaat het erom dat je gegevens kunt valideren en er eenvoudiger mee kunt werken. Het kan in vele situaties handig zijn, maar zeker ook als je met API's werkt waar je gegevens mee wilt uitwisselen. Bekijk de documentatie van Pydantic om er meer over te leren.

In Python zijn er verschillende gegevenstypes, zoals getallen en tekst, maar ook complexere types zoals lijsten en woordenboeken. Elk type bepaalt wat je ermee kunt doen. Met behulp van klassen kan je zelfs je eigen gegevenstypes maken. Python controleert niet op het juist gebruik van deze types, wat voor onverwachte bugs in je code kan zorgen. Gelukkig zijn er Type Hints om je te helpen deze fouten te voorkomen. In dit artikel leer je wat type hints zijn, maar om het waarom te begrijpen, leer je vooral over wat gegevenstypes zijn en hoe en wanneer Python gegevenstypes controleert.

Gegevenstypes

Programmeren is het werken met gegevens, en elk gegeven heeft een bepaald type. Je kunt bijvoorbeeld werken met getallen, of met tekst. Afhankelijk van het gegevenstype kun je bepaalde handelingen wel of niet uitvoeren. Met getallen kun je rekenen, met tekst niet. Getallen en tekst zullen vrij intuïtief aanvoelen, daar heb je in het dagelijkse leven ook mee te maken. Maar er zijn ook complexere gegevenstypes. In Python heb je bijvoorbeeld de list, een lijst met verschillende elementen. Of de dict, een container met sleutel-waarden paren.

geheel_getal = 1  # int
tekst = "Lorem Ipsum"  # str
mijn_lijst = [1, 2, 3, 4, 5]  # list

# dict
mijn_dict = { 
    "naam": "Guido",
    "rol": "Bedenker van Python",
    "level": 10
}

In bovenstaand voorbeeld maak je eerst een geheel getal aan. Dit is het gegevenstype int (van integer). Daarna maak je een tekst aan, dit heeft het gegevenstype str (van string). Het derde voorbeeld is een list en tot slot maak je een dict aan, kort voor dictionary, ofwel: woordenboek.

Naast de ingebouwde gegevenstypes zoals int, str, float en dict kun je ook je eigen gegevenstypes maken, door klassen te maken. De dict van hierboven zou je ook kunnen vormgeven als:

# Maak een klasse `User` aan
class User:

    def __init__(self, naam, rol, level):
        self.naam = naam
        self.rol = rol
        self.level = level

    def level_up(self):
        self.level += 1


# Maak een instantie van het type `User` aan
guido = User(naam="Guido", rol="Bedenker Python", level=10)
print(type(guido))  #  <class '__main__.User'>

# Level up!
guido.level_up()
print(guido.level)  # 11

De klasse User bepaalt de gegevens van het type (naam, rol, level) en wat je ermee kunt (een level omhoog gaan, in dit geval).

Het belangrijkste om te onthouden is: Een gegevenstype bepaalt wat je met het gegeven kunt doen.

Lees ook het hoofdstuk Eerste stappen uit onze gratis Basiscursus Python om meer te leren over gegevenstypen in Python.

Lees het hoofdstuk Werken met klassen uit onze gratis Basiscursus Python voor meer informatie over het werken met klassen in Python.

Typesystemen

Als je met gegevens - en dus met gegevenstypes - werkt, kunnen er verschillende dingen verkeerd gaan die specifiek met het type te maken hebben. Stel dat je de volgende functie hebt:

def hoofdletters(woord):
    """Zet het gegeven woord om in kapitalen"""

    woord_in_kapitalen = woord.upper()   
    return woord_in_kapitalen

Een eenvoudige functie, die de methode upper gebruikt om het woord in kapitalen om te zetten. Maar... upper is een methode die je alleen op tekst (str) kunt toepassen. Het volgende levert dus geen problemen op:

woord = hoofdletters(woord="test")
print(woord)  # TEST

Maar wat als je nu geen str opgeeft, maar een int?

getal = hoofdletters(woord=10)

# AttributeError: 'int' object has no attribute 'upper'

Je ziet dat als je een verkeerd gegevenstype opgeeft als argument, er een fout ontstaat. Een int heeft namelijk geen methode upper!

Voordat je leert hoe je dit kunt voorkomen, is het belangrijk om te begrijpen hoe verschillende talen omgaan met het controleren van gegevenstypes. Hoe een taal dit implementeert noem je een typesysteem. Je kunt typesystemen langs twee assen indelen:

• Dynamisch of Statisch

• Zwak of Sterk

Dynamisch of Statisch

De eerste as is of een taal gebruik maakt van dynamische of statische typering. Een taal is statisch getypeerd als het type van een variabele tijdens compileren bekend is. Het compileren is het omzetten van de hogere taal (bijvoorbeeld C++) naar een taal die de computer begrijpt (machinetaal of bytecode). Is de taal statisch getypeerd, dan moet elke variabele een type hebben tijdens het compileren. Je ziet statische typering met name - maar niet uitsluitend - bij talen die gecompileerd worden voordat ze uitgevoerd kunnen worden.

Een dynamisch getypeerde taal daarentegen, associeert gegevenstypen met de waarden tijdens de uitvoering van het programma. Vaak - maar niet uitsluitend - is dit bij geïnterpreteerde talen. Een geïnterpreteerde taal voert de broncode regel voor regel uit en zet het tijdens uitvoer om in machinetaal of bytecode.

Compileren en interpreteren zijn ingewikkelde concepten, met veel nuances. Het geeft niet als je het niet 100% begrijpt. Belangrijk is dat je begrijpt dat dynamisch getypeerde talen tijdens uitvoer de types controleren. Statische getypeerde talen doen dit bij compilatie.

Python is een dynamisch getypeerde taal. Je kunt daarom gerust bovenstaande functie hoofdletters definiëren, en er pas tijdens uitvoering achter komen dat er een fout ontstaat als er een int wordt opgegeven als argument.

In een statisch getypeerde taal zou je tijdens het compileren - dus vóór uitvoering - er al achter komen dat er een mogelijke fout is, omdat de compiler weet dat je een int niet in hoofdletters kunt omzetten. Deze bug haal je er dan dus al uit voordat je code wordt uitgevoerd.

Zwak of Sterk

Een tweede as waarop je het typesysteem kunt indelen is of het sterke of zwakke typering betreft. In een zwak getypeerde taal - zoals JavaScript - is onderstaande mogelijk:

10 + "10"
// "1010"

Het resultaat is een tekst, het getal is dus impliciet omgezet van getal naar tekst.

In een sterk getypeerde taal zou dit een fout opleveren, daar kun je (sommige) gegevenstypes alleen expliciet omzetten:

x = 10 + int("10")
print(x)  # 20

Python is een sterk getypeerde taal.

Introducing: Type Hints

Python is een dynamisch getypeerde en geïnterpreteerde taal. Een voordeel hiervan is dat je er snel in kunt ontwikkelen. Je hoeft niet steeds eerst te compileren voordat je uitvoert, en je hoeft je ook niet druk te maken om gegevenstypes. Het nadeel hiervan is dat Python over het algemeen langzamer is dan gecompileerde talen zoals C, C++ of Rust. Een ander nadeel zag je al: bugs die te maken hebben met gegevenstypes komen soms pas tijdens uitvoering naar boven.

Sinds Python 3 is hier gelukkig een oplossing voor: Type Hints. Type hints zijn optionele toevoegingen aan je code waarmee je aangeeft van welk type je variabelen, parameters en return values zijn. Hiermee wordt het mogelijk om met behulp van externe tools je programma statisch te controleren. Hiermee haal je potentiële bugs dus al uit je code voordat het uitgevoerd wordt. Het eerdere voorbeeld kun je herschrijven als:

def hoofdletters(woord: str) -> str:
    """Zet het gegeven woord om in kapitalen"""

    woord_in_kapitalen = woord.upper()   
    return woord_in_kapitalen

woord = hoofdletters("test")
getal = hoofdletters(10)

Op de eerste regel zie je dat de parameter nu verwacht van het type str te zijn, aangegeven met woord: str. Met -> str geef je aan dat de functie altijd een str teruggeeft.

Je kunt nu bijvoorbeeld mypy gebruiken om je code te controleren, vóórdat je de code publiceert / uitvoert.

mypy main.py

main.py:9: error: Argument 1 to "hoofdletters" has incompatible type "int"; expected "str"
Found 1 error in 1 file (checked 1 source file)

Deze type hints zijn optioneel en worden genegeerd door de interpreter. Je kunt ze dus stapsgewijs toevoegen in je bestaande code, de ene functie annoteer je wel, de andere niet.

Overigens is het belangrijk om te onthouden dat je met type hints niet alle bugs opspoort. Stel dat je bovenstaande functie gebruikt met invoer van een gebruik, bijvoorbeeld via een formulier. Die invoer moet je dan nog steeds controleren! Voert de gebruiker een cijfer in, dan zal er nog steeds een fout ontstaan.

Voorbeelden

Het type hints systeem is erg uitgebreid, zie de cheatsheet voor een snel overzicht. Hier volgen een paar voorbeelden om je op gang te helpen.

# Type hint variabelen
woord: str = "Test"
level: int = 10

# Type hints voor `dicts`
mijn_dict: dict[str, int]

# Of als de waarden van verschillende waarden kunnen zijn
from typing import Union

mijn_dict: dict[str, Union[str, int]]

# Of hetzelfde, vanaf Python 3.10
mijn_dict: dict[str, str | int]

# Gebruik Optional voor waarden die `None` mogen zijn
from typing import Optional
x: Optional[str] = None

# Of hetzelfde, vanaf Python 3.10
x: str | None = None

# Gebruik een eigen klasse als type
class User:
    def __init__(self, email):
        self.email = email

def email_user(user: User) -> None:
    # E-mail user
    print(f"E-mail verstuurd naar {user.email}")

Conclusie

Type hints in Python bieden het beste van beide werelden - de flexibiliteit en snelheid van dynamische typering, aangevuld met meer controle en zekerheid door de optionele type hints. Een bijkomend voordeel is dat veel Python IDEs en tools de type hints gebruiken om betere code-analyse en autocomplete te bieden.

Je kunt eenvoudig met type hints beginnen in je projecten, doordat optioneel zijn. Het is prima om sommige stukjes code wel te annoteren, en andere niet. Installeer bijvoorbeeld mypy, en je kunt beginnen!

In een Geautomatiseerd gegevens downloaden heb je geleerd hoe je met requests data kunt ophalen van een URL. In deze tutorial ga je een stapje verder en ga je aan de slag met die data. Je leert werken met het pakket pandas, een veelgebruikte tool voor data-analyse in Python.

Wat is pandas?

pandas is een open-source pakket om data-analyses uit te voeren en data te bewerken. De basis is de zogenaamde DataFrame. Dit is een tabel met rijen en kolommen, vergelijkbaar met een spreadsheet:

Een kolom in pandas is van het gegevenstype Series. De donkergrijze rij bevat de kolomnamen en de donkergrijze eerste kolom bevat de index (rijnummers of namen).

Waarom pandas?

Als je te maken hebt met grote hoeveelheden data in de vorm van CSV-bestanden, Excel-sheets, databases en meer is het prettig om deze data snel en efficiënt te kunnen analyseren en bewerken. Dit is waar pandas goed in is. Met pandas kun je:

• Data importeren/exporteren in veel verschillende formaten (CSV, Excel, SQL, etc.)

• Data opschonen (Missende waarden vervangen, kolommen hernoemen, rijen verwijderen, etc.)

• Data analyseren (groeperen, samenvatten, statistieken berekenen, etc.)

Het grote voordeel van pandas ten opzichte van bijvoorbeeld Excel, is dat het eenvoudiger is om het werken met gegevens te automatiseren. Heb je een Excelbestand waar je eenmalig iets uit nodig hebt, maak dan vooral een draaitabel.

Maar krijg je elke week hetzelfde Excelbestand met nieuwe gegevens, en ben je elke keer die draaitabel opnieuw aan het maken, dan is pandas een uitkomst. Daar komt bij dat het goed in te passen is in een volledig (Python)programma: inlezen van gegevens, opschonen, analyses maken, een rapport maken en dit e-mailen. En dat allemaal automatisch!

Het project

Vervolg op 'Geautomatiseerd gegevens downloaden'

Dit project is een vervolg op Geautomatiseerd gegevens downloaden. Als je dat nog niet hebt gedaan, lees (en maak) dat dan eerst.

In dat project download je data van het KNMI. Dit komt in een txt-bestand. Nadat je het tekstbestand hebt opgeslagen, schoon je het op en sla je het op als CSV-bestand, zodat er eenvoudiger mee is te werken. De data zijn maand- en jaargemiddelde temperaturen van het meetstation De Bilt.

In dit vervolgproject laad je KNMI-gegevens die je in een CSV hebt opgeslagen in met pandas in om er vervolgens een eenvoudige analyses op los te laten. Je kunt verdergaan in het eerdere KNMI-project. Activeer de virtual environment en installeer pandas:

cd projects/knmi
source .venv/bin/activate  # .venv\Scripts\activate.bat voor Windows
python -m pip install pandas
python -m pip freeze > requirements.txt

Aan de slag met pandas

Zodra pandas geïnstalleerd is, kun je het importeren. Het is gebruikelijk om pandas te importeren onder de alias pd. Voeg vervolgens een functie load_data toe aan het project. Dit kan in main.py, maar omdat het project wat uitgebreider wordt kun je het ook in een apart bestand plaatsen. Bijvoorbeeld in data.py. Onder de code lees je de toelichting.

# ...

import pandas as pd

# ...

CSV = "knmi.csv"
KNMI_COLUMNS = {
    "STN": "Station",
    "JAN": "Januari",
    # ... etc
    "DEC": "December",
    "YYYY": "Jaar",
    "YEAR": "Jaargemiddelde",
}

MONTH_COLUMNS = []
for key, value in KNMI_COLUMNS.items():
    if key not in ["STN", "YYYY", "YEAR"]:
        MONTH_COLUMNS.append(value)

def load_data():
    """Laad de gegevens uit het CSV-bestand in een pandas DataFrame en maak enkele aanpassingen."""

    # Maak een DataFrame van het CSV-bestand
    df = pd.read_csv(CSV, delimiter=",")

    # Hernoem de kolommen
    df.rename(columns=KNMI_COLUMNS, inplace=True)

    # Van 0.1 °C naar 1°C
    columns = MONTH_COLUMNS + ["Jaargemiddelde"]
    updated_columns = df[columns].map(lambda x: x / 10, na_action="ignore")
    df[columns] = updated_columns

    # Toon de eerste 5 rijen voor een snelle inspectie
    print(df.head(), "\n")

    return df

In deze functie laad je de gegevens uit de eerder gemaakte CSV in, hernoem je de kolommen en wijzig je de getallen van 0.1 °C naar 1°C (dus 80.5 wordt 8.5). Tot slot gebruik je df.head() om de DataFrame snel te inspecteren.

CSV inlezen

Met pandas kun je eenvoudig gegevens inlezen uit verschillende soorten bestanden, zoals CSV, Excel, JSON, etc. Voor elk bestandsformaat is er de methode read_*. Dus om het CSV-bestand in te lezen gebruik je pd.read_csv(). Je geeft altijd het pad naar het bestand op (in dit geval opgeslagen in de constante CSV) en optioneel andere argumenten. Omdat de KNMI-gegevens zijn opgeslagen in een CSV waarbij de waarden worden gescheiden door een komma, gebruik je delimiter=",". De gegevens worden ingelezen en opgeslagen in de variabele df, die van het type DataFrame is.

Zie de documentatie van read_csv voor alle opties.

Kolommen hernoemen

De kolomnamen bestaan uit Engelse afkortingen, het is mooier voor het resultaat om te werken met de volledige Nederlandse namen. Gebruik df.rename() om dit te doen. Met het argument columns geef je aan welke kolommen je wilt wijzigen. Je geeft een dict mee met de oude en nieuwe namen als key-value pairs. Met inplace=true geef je aan dat df gewijzigd wordt, in plaats van dat er een nieuwe DataFrame wordt teruggegeven.

Van 0.1 °C naar 1°C

De gegevens in het oorspronkelijke formaat zijn in tienden van graden. Dus een gemiddelde temperatuur van 8 graden, staat genoteerd als 80. Omdat we meer gewend zijn in graden te denken, pas je dit aan. Hiervoor maak je eerst een lijst met alle maandnamen, plus de kolom "Jaargemiddelde". Vervolgens wijzig je alle gegevens in die kolommen. Hiervoor gebruik je de volgende code:

columns = MONTH_COLUMNS + ["Jaargemiddelde"]
updated_columns = df[columns].map(lambda x: x / 10, na_action="ignore")
df[columns] = updated_columns

De syntax om een kolom te selecteren is df["kolomnaam"] voor een enkele kolom, of df[["kolomnaam1", "kolomnaam2"]] voor meerdere kolommen. Met df[columns] selecteer je dus alle kolommen met meetgegevens. Vervolgens pas je de methode .map() toe. Deze methode ontvangt een functie als argument die wordt toegepast op elke cel in de kolommen.

Omdat je alle getallen wilt delen door 10, gebruik je map(lambda x: x / 10). Dit ziet er ingewikkeld uit, maar is hetzelfde als:

def deel_door_10(x):
    return x / 10

df[columns].map(deel_door_10, na_action="ignore")

lambda x: x / 10 is een zogenaamde lambda-functie, ofwel een korte functie zonder het eerst te hoeven definiëren.

Met na_action="ignore" geef je aan dat als een cel geen waarde bevat, de functie wordt overgeslagen (anders krijg je fouten).

Je hebt nu een variabele updated_columns met alle aangepaste kolommen. De laatste stap is om de oude kolommen in df te vervangen door de nieuwe kolommen:

df[columns] = updated_columns

Inspecteren

Tot slot print je de eerste vijf rijen van de DataFrame met df.head(). Dit is handig om snel te kijken hoe je data eruit ziet. Het resultaat ziet er ongeveer zo uit:

Een analyse uitvoeren

Je hebt gezien dat je met pandas data kunt inladen en transformeren. Je kunt nu een (eenvoudige) analyse maken, bijvoorbeeld het ophalen van de hoogste jaargemiddelde temperatuur:

def get_highest_mean_temp(df):
    """
    Haal de hoogste jaargemiddelde temperatuur op.
    """

    # Haal de hoogste jaargemiddelde temperatuur op
    highest_mean_temp = df["Jaargemiddelde"].max()  # Temperatuur in °C
    index = df["Jaargemiddelde"].idxmax()  # Index van de rij met de hoogste temperatuur
    year = df.at[index, "Jaar"]  # Jaar van de hoogste temperatuur

    print(f"Hoogste jaargemiddelde: {highest_mean_temp}°C")
    print(f"Dit was in jaar: {year}")

    return highest_mean_temp, year

Eerst selecteer je de juiste kolom met df["Jaargemiddelde"]. Vervolgens haal je hier het hoogste getal uit op met .max(). Omdat je ook het bijbehorende jaar wilt weten, doe je hetzelfde nog een keer, maar nu met .idmax(). Dit haalt de index op van de rij met het hoogste getal.

Je kunt nu het jaar ophalen met df.at[], waarbij je de zojuist opgehaalde index als eerste waarde opgeeft, en de kolomnaam "Jaar" als tweede waarde. Zo selecteer je de cel uit de rij met de hoogste temperatuur de kolom "Jaar".

Conclusie

pandas is een krachtige tool voor data-analyse in Python. Het biedt veel mogelijkheden waarmee je data kunt importeren, exporteren, opschonen en analyseren. In deze tutorial heb je het topje van de ijsberg gezien van wat mogelijk is. Werk je veel met spreadsheet-achtige gegevens (zoals CSV of Excel), dan is pandas alleen al handig voor het opschonen en transformeren van deze gegevens.

import json
import requests

URL = "https://opendata.cbs.nl/ODataApi/odata/85496NED/TypedDataSet"

def get_data(refresh=True):
    if not refresh:
        try:
            with open("data.json") as f:
                data = json.load(f)
        except FileNotFoundError:
            print("Bestand niet gevonden, downloaden")

            # Roep deze functie aan, met `refresh=True`
            return get_data(refresh=True)
    else:
        response = requests.get(URL)

        # Als de HTTP-code 400 of hoger is, zal er een uitzondering worden opgeworpen
        response.raise_for_status()
        data = response.json()

        # Sla bestand op
        with open("data.json", "w") as f:
            json.dump(data, f, indent=2)

    return data

Dit werkt prima, maar er is een handigere manier. Met requests-cache stel je eenvoudig in hoe lang je de HTTP-responses wilt cachen. Vervolgens kun je de code gelijk houden, en zal bijvoorbeeld een GET alleen uitgevoerd worden als de cache verlopen is.

Bovenstaand voorbeeld kun je eerst herschrijven naar een eenvoudigere versie zonder (handmatige) caching:

import json
import requests

URL = "https://opendata.cbs.nl/ODataApi/odata/85496NED/TypedDataSet"

def get_data():
    response = requests.get(URL)

    # Als de HTTP-code 400 of hoger is, zal er een uitzondering worden opgeworpen
    response.raise_for_status()
    data = response.json()

    # Sla bestand op
    with open("data.json", "w") as f:
        json.dump(data, f, indent=2)

    return data

Vervolgens voeg je een cache toe met requests-cache.

from datetime import datetime, timedelta
import json
import requests_cache

URL = "https://opendata.cbs.nl/ODataApi/odata/85496NED/TypedDataSet"

now = datetime.now()
tonight = datetime(now.year, now.month, now.day) + timedelta(days=1)

def get_data():
    session = requests_cache.CachedSession(expire_after=tonight)
    response = session.get(URL)

    # Als de HTTP-code 400 of hoger is, zal er een uitzondering worden opgeworpen
    response.raise_for_status()
    data = response.json()

    # Sla bestand op
    with open("data.json", "w") as f:
        json.dump(data, f, indent=2)

    return data

Boven de functie definieer je eerst tonight, ingesteld op 00:00 van de volgende dag. Dus roep je het script op 11 maart om 15:00 aan, dan is tonight gelijk aan 12 maart, 00:00.

In plaats van response = requests.get(url) maak je de HTTP-request met response = session.get(url). Die sessie maak je eerst aan, en je stelt in wanneer de cache moet verlopen. In dit geval stel je het in op tonight (00:00).

De rest van de functie hou je gelijk.

Roep je deze functie nu meerdere malen aan op een dag, dan zal het de eerste keer de data downloaden, maar bij elke volgende aanroep de opgeslagen response gebruiken. Roep je de functie een dag later weer aan (na 00:00), dan zal het de data de eerste keer wel weer downloaden.

Standaard gebruikt requests-cache een sqlite database om de response in op te slaan. Lees de documentatie om te leren hoe je andere opslagmethoden gebruikt en om meer te leren over requests-cache.

Wat is programmeren?

Voordat we ingaan op de toekomst van programmeren in de wereld van AI, is het belangrijk vast te stellen wat programmeren eigenlijk is. Als je bijvoorbeeld kijkt naar de uitleg op Wikipedia zie je dat de focus erg ligt op het schrijven van de code:

Programmeren is het schrijven van een computerprogramma, een concrete reeks instructies die een computer kan uitvoeren. Dit is de taak van een softwareontwikkelaar of programmeur.

Maar wat belangrijk is om te onthouden, is dat er heel wat werk nodig is rondom het schrijven van code. Bijvoorbeeld:

• Het probleem dat je wilt oplossen goed definiëren

• Wensen en eisen van gebruikers ophalen

• Deze wensen en eisen vertalen naar mogelijke oplossingen

• Deze mogelijke oplossingen tegen elkaar afwegen

• Prioriteren wat je eerst gaat doen

• Afstemmen met collega's

• Afstemmen met opdrachtgevers

• Je tussentijdse resultaten demonstreren, feedback ophalen

• ...

Eén van de moeilijkere dingen binnen het programmeren is de wensen en eisen scherp krijgen. Stel dat je werkt aan een systeem waar gebruikers hun projecten kunnen beheren. De opdrachtgever komt met een wens: "Ik wil dat gebruikers een project kunnen kopiëren naar een nieuw project". Ok, een paar vragen:

• Wat moet er allemaal gekopieerd worden? Alle openstaande items, afgehandelde items, naam, deadlines, projectmedewerkers?

• Moeten er voor het kopiëren wijzigingen gemaakt kunnen worden? Welke?

• Hoe zien de stappen eruit? Vanuit waar wordt er gekopieerd? Hoe zien alle schermen eruit?

• Kan iedereen een kopie maken? Of alleen beheerders? Van welke projecten wel, van welke niet?

• En zo nog 100 vragen.

Voordat je code kunt schrijven moeten al deze vragen helder zijn, anders weet je niet welke code je moet schrijven. Programmeren is uiteindelijk het vertalen van de intentie van de maker naar instructies die een computer kan gebruiken. Dit vertalen van intentie naar computercode vraagt een precieze en exacte taal. Oftewel: een programmeertaal.

Wat kan AI wel en niet?

De huidige generatie AI kan dit vertalen van intentie naar computercode niet. Je kunt wel de opdracht geven: "Schrijf code dat ervoor zorgt dat de gebruiker een bestaand project naar een nieuw project kan kopiëren". En de AI zal moeiteloos code genereren. Maar of het goed is, is maar de vraag. Afhankelijk van het model zal het best ver kunnen komen, zeker als het de context van de rest van je code kent. Het ziet dat het project in Python is geschreven, het ziet dat je met Django werkt en herkent de algemene structuur van een scherm. Maar dit is allemaal al veel gevraagd. En dan nog. Het stelt niet al die bovenstaande vragen: wie moet er kunnen kopiëren? Welke projecten wel, welke niet? Welke elementen wel, welke niet? Etc. Dit zou je dan allemaal in de opdracht moeten meegeven.

Wat AI wel heel goed kan is bijvoorbeeld jouw code lezen, en suggesties doen voor testen. Of jouw code lezen en suggesties doen voor verbeteringen. Ook kun je AI afgebakende instructies geven: schrijf een functie die deze parameters als input heeft en dit als resultaat geeft. Maar ook hier geldt: je moet precies zijn om de gewenste resultaten te krijgen. Toch kom je hiermee een heel eind. Sommige modellen kunnen ook heel goed suggesties doen in jouw code, op basis van de omliggende code. De AI begrijpt waar je aan werkt, en wat er nog nodig is.

Maar in alle gevallen geldt: jij als programmeur hebt dan al bedacht wat de wensen en eisen zijn en hoe die vertaald moeten worden naar code. Het code schrijven gaat met behulp van AI sneller en makkelijker, maar een belangrijk deel (het nadenken) doe je dus nog zelf.

Bovendien is AI (nog) niet foutloos. Een bekend fenomeen is het zogenaamde "hallucineren": de AI weet niet precies wat het moet doen, en verzint maar wat. Dit kan soms subtiel zijn. Gebruik je AI om code te schrijven, dan is het dus heel belangrijk dat je het altijd zelf nog controleert. En om dat te kunnen doen moet je wel weten hoe het in elkaar steekt, anders haal je de (subtiele) fouten er niet uit.

Conclusie

Kortom: AI is een geweldig hulpmiddel, maar momenteel niet meer dan dat. Het is een soort autocomplete on steroids. Het kan zeker het proces van het code schrijven versnellen, en je kunt er zelfs van leren. Bijvoorbeeld door te vragen: hoe kan ik mijn code beter maken?

Maar vooralsnog is AI geen complete vervanging van een programmeur, omdat een AI niet de intentie van een klant, gebruiker of opdrachtgever kan omzetten naar code. Wie weet kan dit in de toekomst wel, dan kan de AI niet alleen code genereren, maar ook heel goed uitvragen wat de precieze wensen zijn. Maar zover zijn we nog niet, en dus is het zeker nog zinvol om te leren programmeren. Al is het maar om de code die AI genereert te kunnen controleren.

Niemand kan in de toekomst kijken. Maar voorlopig durf ik de stelling wel aan dat het zeker nog zinvol is om te leren programmeren!

Het project

Het Centraal Bureau voor de Statistiek (CBS) maakt alle gegevens niet alleen via de website beschikbaar, maar ook via een API (https://opendata.cbs.nl/statline/portal.html). In dit project download je de bevolkingsgegevens, sla je ze op in data.json en verwerk je ze vervolgens om per jaar het totale bevolkingsaantal van Nederland te tonen.

output

1950: 10.026.773
1951: 10.200.280
...
2022: 17.590.672
2023: 17.811.291

Voordat je begint

Maak een nieuw project aan, met een nieuwe virtual environment. Installeer daarin de benodigde packages:

shell

cd projects
mkdir cbs_json && cd cbs_json
python -m venv .venv
source .venv/bin/activate  # .venv\Scripts\activate.bat voor Windows
python -m pip install requests
python -m pip freeze > requirements.txt

Wat is JSON?

JSON staat voor JavaScript Object Notation. Het is een lichtgewicht dataformaat dat makkelijk voor mensen te lezen en schrijven is en makkelijk voor machines om te genereren en analyseren. Het wordt veel gebruikt om gegevens tussen programma's uit te wisselen, met name via internet. Veel API's zullen dan ook JSON teruggeven.

In onderstaand voorbeeld van de Wikipediapagina over JSON, zie je een lijst met twee elementen:

json

[
   {
      "Naam":"JSON",
      "Type":"Gegevensuitwisselingsformaat",
      "isProgrammeertaal":false,
      "Zie ook":[
         "XML",
         "ASN.1"
      ]
   },
   {
      "Naam":"JavaScript",
      "Type":"Programmeertaal",
      "isProgrammeertaal":true,
      "Jaar":1995
   }
]

Zoals je ziet, lijkt een JSON-object erg op een dict in Python. Net als een dict wordt een JSON-object omsloten door curly braces ({}) en bestaat het uit sleutel-waarden paren. Er zijn wel een aantal beperkingen. Als waarde zijn alleen de volgende datatypes toegestaan:

• Tekst

• Getallen

• true, false en null

• Lijsten (arrays, [])

• Andere JSON-objecten ({})

De sleutels zijn altijd tekst.

JSON in Python

Python heeft een ingebouwde bibliotheek genaamd json voor het werken met JSON-data. Er zijn twee manieren om dit te doen: van en naar strings en van en naar bestanden:

• Van Python naar een JSON-string: json.dumps()

• Van Python naar een JSON-bestand: json.dump()

• Van een JSON-string naar Python: json.loads()

• Van een JSON-bestand naar Python: json.load()

Van Python naar JSON noem je serialiseren. Van JSON naar Python noem je deserialiseren.

Verder met het project

Nu je de basis van JSON begrijpt, kun je verder met het project.

Gegevens downloaden

Stap 1 is het downloaden van de gegevens. Doe dit met requests. Maak in main.py een functie aan om de gegevens te downloaden. Deze functie is vrijwel gelijk aan de get_html functie uit Een website scrapen met Beautiful Soup.

main.py

import json
import requests

URL = "https://opendata.cbs.nl/ODataApi/odata/85496NED/TypedDataSet"

def get_data(refresh=True):
    if not refresh:
        try:
            with open("data.json") as f:
                data = json.load(f)
        except FileNotFoundError:
            print("Bestand niet gevonden, downloaden")

            # Roep deze functie aan, met `refresh=True`
            return get_data(refresh=True)
    else:
        response = requests.get(URL)

        # Als de HTTP-code 400 of hoger is, zal er een uitzondering worden opgeworpen
        response.raise_for_status()
        data = response.json()

        # Sla bestand op
        with open("data.json", "w") as f:
            json.dump(data, f, indent=2)

    return data

De functie zorgt ervoor dat je het bestand opslaat als data.json, zodat je tijdens het ontwikkelen niet steeds de URL hoeft aan te roepen. Wil je de gegevens verversen, roep dan get_data aan met refresh=True.

De gearceerde regels laten zien je waar je in de code met json werkt. Als je data.json wilt inladen, gebruik je json.load(). Haal je de gegevens eerst op van het CBS met requests, dan gebruik je data = response.json(). Dit is een hulpmiddel van requests om inkomende json om te zetten naar een Python-object. Sla je het bestand vervolgens op, dan gebruik je json.dump(data, f, indent=2). Dus: je serialiseert het Python-object data naar bestand f. Om het leesbaar te maken gebruik je een indentatie van 2.

Roep de functie eens aan en inspecteer het opgeslagen bestand:

main.py

# ...

if __name__ == "__main__":
    data = get_data()

Het resultaat ziet er ongeveer zo uit:

Alle gegevens zijn te vinden in de sleutel value, welke een lijst bevat met JSON-objecten. Elk jaar is één object. Voor dit project heb je uit die objecten alleen de sleutels Perioden en TotaleBevolking_1 nodig.

Gegevens verwerken

Nu je de gegevens in data.json beschikbaar hebt, kun je datgene eruit halen wat je nodig hebt. Maak een functie get_total_population aan in main.py.

main.py

# ...

def get_total_population():

    # Open het bestand
    with open("data.json") as f:
        data = json.load(f)  # data is nu een Python object (dict)

    # Bereid een lege lijst voor
    result = []

    # Loop door de rijen in de data
    for item in data["value"]:
        year = item["Perioden"].split("JJ")[0]  # Schoon het jaartal op
        value = item["TotaleBevolking_1"]

        # Voeg het jaartal en de waarde toe aan de lijst als een tuple
        result.append((year, value))

    return result

Je begint met het inladen van het JSON-bestand, wat zal resulteren in een dict. Vervolgens loop je over alle items in de data["value"] lijst om er het jaar (Perioden) en de bevolkingsomvang (TotaleBevolking_1) uit te halen. Schoon het jaar op, zodat je in plaats van "1950JJ00" netjes "1950" krijgt.

Roep het geheel tot slot aan en druk de resultaten af:

main.py

import locale
locale.setlocale(locale.LC_ALL, "nl_NL.utf8")
# ...

if __name__ == "__main__":
    data = get_data(refresh=False)  # Zet op False om niet steeds te downloaden
    total_population = get_total_population()

    for year, value in total_population:
        print(f"{year}: {value:n}")

Bovenaan je bestand stel je locale in, zodat je op de laatste regel {value:n} kunt gebruiken om duizendtallen netjes te scheiden door een punt.

Het resultaat:

Conclusie

Werken met JSON in Python is eenvoudig te doen met de json package, beschikbaar in de standaard bibliotheek. Het omzetten van Python-objecten naar JSON doe je met dump of dumps. Het omzetten van JSON naar Python doe je met load of loads. Vaak zul je JSON ophalen via een API. Gebruik je hiervoor requests, dan kun je response.json() gebruiken om de inkomende data te converteren naar een Python-object.

Het project

In dit project download je data van het KNMI. Dit komt in een txt-bestand. Nadat je het tekstbestand hebt opgeslagen, schoon je het op en sla je het op als CSV-bestand, zodat er eenvoudiger mee is te werken. De data zijn maand- en jaargemiddelde temperaturen van het meetstation De Bilt. De url is:

https://cdn.knmi.nl/knmi/map/page/klimatologie/gegevens/maandgegevens/mndgeg_260_tg.txt

Voordat je begint

Lees voordat je begint nog eens Werken met pip en venv door als een opfrisser nodig hebt over hoe je een virtual environment aanmaakt en daarin packages installeert.

Maak vervolgens een nieuw project aan en installeer requests:

shell

cd projects
mkdir knmi && cd knmi
python -m venv .venv
source .venv/bin/activate  # .venv\Scripts\activate.bat voor Windows
python -m pip install requests
python -m pip freeze > requirements.txt

Data downloaden met requests

requests is een package dat het werken met urls eenvoudig maakt. In hun eigen woorden:

Requests is an elegant and simple HTTP library for Python, built for human beings.

Maak een main.py aan maak daarin een eenvoudige download-functie.

main.py

import requests

URL = "https://cdn.knmi.nl/knmi/map/page/klimatologie/gegevens/maandgegevens/mndgeg_260_tg.txt"
TXT = "knmi.txt"

def download():
    response = requests.get(URL)

    # Als de HTTP-code 400 of hoger is, zal er een uitzondering worden opgeworpen
    response.raise_for_status()  

    # Sla het bestand op
    with open(TXT, "w", encoding="utf-8") as file:
        file.write(response.text)

Je ziet hoe eenvoudig requests werkt. Met response.raise_for_status() controleer je of de HTTP-code lager is dan 400. Zo niet, dan wordt er een uitzondering opgeworpen. Alles in de 4XX en 5XX reeks betekent namelijk dat er iets niet goed ging. Zie de lijst met HTTP-codes voor meer informatie.

Je slaat het bestand op de huidige locatie op (dus naast main.py). Met "w" geef je aan dat je het bestand wilt schrijven. Let op: als het bestand al bestaat, zal het hierdoor worden overschreven!

Voeg tot slot onderaan in main.py het volgende toe:

main.py

if __name__ == "__main__":
  download()

Je kunt het bestand nu uitvoeren in je shell met python main.py. Als het goed is, is er nu een bestand knmi.txt opgeslagen. Open het bestand met een teksteditor naar keuze om te inspecteren.

Je ziet dat het tekstbestand de koppen (eerste gele markering) en gegevens (tweede gele markering) bevat, maar begint met een toelichtende tekst. Als je geautomatiseerd wilt werken met de gegevens, heb je deze tekst niet nodig. Tijd voor de volgende stap!

Het bestand opschonen

Er zijn drie problemen met het tekstbestand.

Ten eerste de al eerder genoemde toelichtende tekst, die heb je niet nodig. Ten tweede is er een lege regel (niet heel erg, maar nu je toch bezig bent...). En tot slot is het bestand netjes opgemaakt in kolommen, waardoor er veel spaties zijn toegevoegd. Zou je het zo omzetten naar CSV, dan zouden die spaties onderdeel worden van de gegevens.

Uiteindelijk wil je een regel alleen behouden als het de koppen bevat óf als het de gegevens bevat. De gegevens wil je opschonen door de spaties te verwijderen. Maak een functie clean_data aan in main.py:

main.py

# ...

TXT = "knmi.txt"
CSV = "knmi.csv"

# ...

def clean_data():
    # Open het tekstbestand
    with open(TXT, "r", encoding="utf-8") as file:
        lines = []
        for line in file:
            # Behoud alleen de koppen en de rijen met gegevens
            if line.startswith("STN,YYYY") or line.startswith("260"):
                # Verwijder spaties
                lines.append(line.replace(" ", ""))

    # En sla op als CSV-bestand
    with open(CSV, "w", encoding="utf-8") as file:
        file.writelines(lines)

# ....

Met deze functie behoud je alleen de regels die relevant zijn en schrijf je ze naar een CSV-bestand. Na het openen van het tekstbestand maak je een lege list aan, waarin je de gewenste regels gaat toevoegen.

Een regel wil je alleen behouden als het de koppen bevat (begint met "STN,YYYY") of als het de gegevens bevat (begint met "260"). Als dit zo is, voeg je de regel toe aan lines, nadat je de spaties hebt verwijderd met line.replace(" ", """).

STN,YYYY?

Kun je ook bedenken waarom we testen op "STN,YYYY" om de regel met koppen te bewaren, en niet simpelweg op "STN"?

Tot slot maak je een nieuw CSV-bestand aan in schrijf-modus. Je schrijft met file.writelines(lines) alle regels naar het bestand, en klaar!

Voeg clean_data toe aan het if __name__ == __main__ blok.

main.py

# ...

if __name__ == "__main__":
    download()
    clean_data()

Voer het weer uit vanuit je shell met python main.py. Open het bestand in een teksteditor om te bekijken.

Je ziet een netjes komma-gescheiden bestand. Je kunt het nu ook openen in een spreadsheet programma zoals Microsoft Excel of LibreOffice Calc om het verder te inspecteren.

Conclusie

Je hebt geleerd dat je met een klein Python-script eenvoudig gegevens kunt downloaden met requests en ze vervolgens kunt opschonen. In dit voorbeeld worden de gegevens elke maand bijgewerkt. Met een eenvoudige python main.py download je zo de laatste gegevens en is het klaar voor gebruik. Uiteraard kun je het script naar eigen inzicht uitbreiden of aanpassen, bijvoorbeeld door de bestanden een naam met de huidige datum erin mee te geven of een paar statistieken te draaien.

Succes!

Het is aan te raden om packages te installeren in een eigen omgeving behorende bij het project waaraan je werkt. Je kunt ze wel systeembreed installeren, maar dit kan voor problemen zorgen. Stel dat je aan twee projecten werkt, die beiden requests nodig hebben. Installeer je requests nu systeembreed, dan zijn beide projecten gedwongen altijd dezelfde versie van requests te gebruiken. Maar misschien kan het ene project nog niet naar de nieuwste versie, om wat voor reden dan ook. Dan ben je gedwongen in al je projecten op de oude versie te blijven.

Daarom kun je het best per project werken met een zogenaamde virtual environment. Een virtual environment is een afgeschermde omgeving per project, waarin de packages worden geïnstalleerd. In project A kun je zo de laatste versie van requests installeren, terwijl je het in project B houdt bij een oudere versie. Je maakt virtual environments met venv.

In deze tutorial leer je werken met venv en pip.

Controleren of pip en venv beschikbaar zijn

Voordat je verdergaat met de tutorial is het belangrijk te controleren of pip en venv beschikbaar zijn.

pip

Er zijn meerdere manieren om packages te installeren. Door Python zelf wordt pip aanbevolen, en sinds Python 3.4 is pip standaard onderdeel van Python-installaties. Het is (hierdoor) de meest gebruikte methode om packages te installeren. Als je een recente versie van Python (3.4 of hoger) hebt geïnstalleerd via python.org, dan heb je pip tot je beschikking. Je kunt dit als volgt controleren:

shell

python -m pip --help

Als je een uitleg krijgt, is pip beschikbaar. Zo niet, update dan Python.

venv

Er zijn ook meerdere manieren om virtual environments te maken, maar ook hier leer je weer hoe te werken met de aanbevolen en ingebouwde manier: venv. Net als bij pip geldt: als je een recente versie van Python hebt geïnstalleerd, is venv bijgesloten. Controleer dit met:

shell

python -m venv --help

Als je een uitleg krijgt, is venv beschikbaar. Zo niet, update dan Python.

Als alles werkt, kun je verder met de tutorial.

Virtual environments aanmaken

Een virtual environment maak je aan met venv. Het maakt een afgeschermde omgeving op basis van de Python-versie waarmee je venv aanroept. Als je meerdere Python-versies hebt geïnstalleerd, kun je dus kiezen met welke Python-versie je de omgeving wilt aanmaken. Op mijn laptop heb ik bijvoorbeeld twee versies beschikbaar:

shell

python --version  # 3.10.12
python3.12  --version  # 3.12.1
````

Ik wil met de standaardversie (3.10) een *virtual environment* maken. Het is mijn gewoonte om de *virtual environment* aan te maken in mijn projectmap. In mijn shell maak ik eerst een lege projectmap aan, en `cd` erheen.

```{.shell title="shell"}
cd projects
mkdir my-project && cd my-project

Vervolgens maak ik een virtual environment aan:

shell

python -m venv .venv

Ik geef de virtual environment de naam .venv (door de voorlopende punt is het een verborgen map), maar je kunt het elke andere naam geven. Gebruikelijk is wel om het venv of .venv te noemen.

De afgeschermde omgeving is nu gemaakt, maar nog niet actief. Dit is belangrijk. Voer je nu python uit, dan zal het nog steeds de systeembrede Python gebruiken. Om te werken binnen de afgeschermde omgeving, moet je het eerst activeren. Hoe je dit doet is afhankelijk van de shell die je gebruikt:

Ik werk met Linux, dus ziet het er als volgt uit:

shell

source .venv/bin/activate

Je kunt een omgeving weer deactiveren met deactivate.

Packages installeren

Nu je een actieve virtual environment hebt, kun je hierin packages installeren. Omdat je net bent beginnen, zijn er slechts twee packages geïnstalleerd, namelijk pip en setuptools. Deze worden standaard geïnstalleerd door venv.

shell

pip list

Package    Version
---------- -------
pip        22.0.2
setuptools 59.6.0

Installeer nu requests en controleer en voer nogmaals pip list uit:

shell

pip install requests

...

pip list

Package            Version
------------------ ----------
certifi            2023.11.17
charset-normalizer 3.3.2
idna               3.6
pip                22.0.2
requests           2.31.0
setuptools         59.6.0
urllib3            2.1.0

Je ziet dat er naast requests nog een aantal packages zijn geïnstalleerd. Dit komt omdat requests deze heeft aangemerkt als afhankelijkheden. Het installeren van requests zal dus ook deze afhankelijkheden installeren.

Requirements opslaan

Het is handig om de packages die je in je project gebruikt, te noteren zodat ze eenvoudig geïnstalleerd kunnen worden. Dit is handig voor jezelf, als je bijvoorbeeld je virtual environment weggooit en alles opnieuw wilt installeren. Maar het is zeker ook handig als met meerdere personen aan één project werkt, of als je jouw project later wilt publiceren. De gebruikers van je project weten dan welke afhankelijkheden ze moeten installeren.

De standaard manier hiervoor is om je afhankelijkheden op te slaan in requirements.txt. Dit kan eenvoudig met pip:

shell

pip freeze > requirements.txt

Het resultaat is een tekstbestandje met alle packages (en hun afhankelijkheden) die je hebt geïnstalleerd:

requirements.txt

# requirements.txt
certifi==2023.11.17
charset-normalizer==3.3.2
idna==3.6
requests==2.31.0
urllib3==2.1.0

In dit geval zijn alle afhankelijkheden vastgezet op een specifiek versie. Je kunt dit wijzigen, en bijvoorbeeld aangeven dat je requests vanaf versie 2 wilt hebben, maar niet hoger dan versie 3:

requirements.txt

...
requests >=2.0, <3
...

Gooi je nu je virtual environment weg, dan kun je alles eenvoudig opnieuw installeren.

shell

# Verwijder .venv
deactivate
rm -rf .venv

# Maak .venv opnieuw aan en activeer
python -m venv .venv
source .venv/bin/activate

# Installeer alles opnieuw
pip install -r requirements.txt

Bekijk je nu weer de lijst met geïnstalleerde packages, dan is alles weer aanwezig:

shell

pip list

Package            Version
------------------ ----------
certifi            2023.11.17
charset-normalizer 3.3.2
idna               3.6
pip                22.0.2
requests           2.31.0
setuptools         59.6.0
urllib3            2.1.0

Verder lezen

In deze tutorial leerde je de basis van het werken in een virtual environment en packages installeren met pip. Met die basis kun je nu verder, maar er is veel meer mogelijk:

• Packages met een specifiek versie installeren

• In requirements.txt aangeven dat je alles binnen de major versie wilt installeren

• Geïnstalleerde packages upgraden met pip

• Packages verwijderen

• ...

De documentatie van pip is uitgebreid en goed leesbaar. Voor het aangeven van welke versie je wilt installeren, lees je deze paragraaf op packaging.python.org. Voor het werken met venv lees je de documentatie van python.