Een CLI met echte argumenten, uitvoer en foutstatus

De afzonderlijke projectmodules kunnen lezen, rekenen en publiceren. Een command-line-interface verbindt die mogelijkheden met wat een gebruiker kiest. Zij moet duidelijke argumenten aannemen en pas na een geslaagde publicatie melden dat het rapport er is.

De opdracht begint met expliciete keuzes

Onze CLI heet urenrapport. De twee verplichte posities zijn de invoerbron en de rapportnaam. Opties kiezen de uitvoermap, JSON of CSV en eventueel een begin- of einddatum.

import argparse

parser = argparse.ArgumentParser(prog='voorbeeld', allow_abbrev=False)
parser.add_argument('source')
parser.add_argument('--format', choices=['json', 'csv'], default='json')
args = parser.parse_args(['registraties.csv', '--format', 'csv'])
print(args.source)
print(args.format)

registraties.csv
csv

Het voorbeeld geeft een lijst expliciet aan parse_args. Dat maakt dezelfde parser bruikbaar in een directe proef, zonder de echte sys.argv van het omringende programma te veranderen. Wanneer main geen argv ontvangt, mag argparse juist de echte programmaregel gebruiken.

De optie allow_abbrev=False houdt de afgesproken optienamen volledig. Een kort stukje zoals --sta wordt niet ongemerkt een geldige nieuwe schrijfwijze van --start. De choices bij --format beperken de toegestane keuzen meteen.

Vertalen aan de ingang, daarna doorgeven

Een argument uit argparse is eerst tekst. Zet aanwezige datumopties met parse_day om naar de interne kalenderdatum. Een niet gekozen grens blijft None.

Daarna roept de CLI de regiefunctie aan. Die functie verbindt de bestaande lees-, reken- en uitvoermodule al. De CLI gaat de bron niet opnieuw lezen en berekent de teamtotalen niet nogmaals uit de ontvangen uitvoertekst.

De optionele keywordafhankelijkheid run gebruikt normaal run_report. Een test kan daar een gecontroleerde foutgevende functie invullen om precies de grensafhandeling te bekijken. Dat vervangt niet de echte I/O-proeven uit de vorige lessen.

Succes heeft een moment en een status

De regie levert een bestemming en rapport terug nadat publiceren geslaagd is. Gebruik die echte gegevens voor de korte succesmelding. Een vaste melding met de demo-aantallen zou bij een andere bron onjuist zijn.

De functie main geeft bij succes het gehele getal nul terug. Het meegeleverde hours.__main__ vertaalt die waarde met SystemExit naar de programmastatus wanneer het pakket met python -m hours wordt gestart. De status is daardoor ook bruikbaar voor een ander programma dat onze CLI aanroept.

Een argumentenfout is al van de parser

import argparse

parser = argparse.ArgumentParser(prog='voorbeeld', allow_abbrev=False)
parser.add_argument('source')
parser.parse_args([])

the following arguments are required: source

Het voorbeeld stopt met status twee en een echte gebruiksmelding op stderr. Argparse verzorgt dat gedrag voor ontbrekende posities of ongeldige opties. Je hoeft er geen tweede zelfgeschreven parser of vaste fouttekst naast te zetten.

Projectfouten ontstaan pas wanneer datums worden omgezet of de opdracht wordt uitgevoerd. Voor InputError, OSError en UnicodeError print onze CLI een melding die met Fout: begint op stderr en geeft zij twee terug. Zo blijven normale uitvoer en een probleemmelding afzonderlijk bruikbaar.

Veelgemaakte fout: iedere uitzondering als invoerfout melden

Een brede except kan ook een programmeerfout verbergen, zoals het verkeerd aanroepen van een functie. Die fout wordt dan ten onrechte gepresenteerd alsof de gebruiker zijn CSV moet aanpassen. Vang daarom alleen de afgesproken foutfamilies; andere fouten en onderbrekingen blijven hun eigen object en betekenis houden.

Importeren is geen gebruikersopdracht

Een test of ander onderdeel mag hours.cli importeren zonder meteen een bestand te verwerken. De startactie staat daarom in hours.__main__, apart van de functiedefinities. Importeren geeft geen succesmelding en maakt geen rapport.

Met die scheiding kunnen de volgende regressieproeven de complete opdracht direct aanroepen. Zij hoeven geen proces of netwerkverbinding na te bootsen. De echte bron, het rapport en de foutstatus blijven controleerbaar.

Samenvatting

• Argparse verwerkt de gekozen argumenten; de regiefunctie doet de echte opdracht.
• Een succesmelding volgt op geslaagde publicatie en status nul.
• Verwachte fouten gaan naar stderr met status twee; importeren start niets.