Instalare și primul script

Lectură estimată: 14 minute

Estimare pentru text, la un ritm de 180 de cuvinte pe minut. Timpul pentru analizarea codului, exerciții și proiecte se adaugă separat și depinde de ritmul tău.

De la o comandă la un program pe care îl poți repeta

Imaginează-ți că primești în fiecare săptămână un tabel cu cereri. Unele sume sunt valide, altele lipsesc, iar câteva identificatoare se repetă. Dacă repari tabelul manual, rezultatul depinde de atenția ta și este greu să explici ce ai schimbat. Un script poate aplica aceeași regulă de fiecare dată și poate arăta separat cazurile respinse. Acesta este proiectul către care construim cursul: un raport CSV verificabil, folosind date fictive.

Înainte să citim fișiere și să calculăm totaluri, avem nevoie de un punct de pornire sigur: să știm ce program rulează, unde se află sursa și cum observăm rezultatul. În această lecție pregătim un director de lucru, executăm un mesaj de întâmpinare și construim o comandă mică pentru planificarea studiului. Nu ai nevoie de un serviciu online, de o cheie API sau de pachete externe.

Obiectivul practic nu este să memorezi toate comenzile. La final trebuie să poți închide terminalul, să îl deschizi din nou și să reproduci rezultatul folosind propriile notițe. Dacă programul funcționează doar după câteva apăsări pe un buton din editor, dar nu știi ce fișier a fost lansat, mediul nu este încă înțeles suficient pentru următoarele lecții.

Cele patru lucruri pe care le folosim

Editorul este aplicația în care scrii și salvezi textul programului. Fișierul cu extensia .py este sursa. Interpretorul Python este programul care execută instrucțiunile din sursă. Terminalul este interfața în care îi ceri sistemului să pornească interpretorul cu anumite argumente. Aceste lucruri colaborează, dar nu sunt interschimbabile.

O confuzie frecventă apare când scrii o comandă precum python salut.py într-o fereastră care afișează >>>. Acolo ești deja în sesiunea interactivă Python. Comanda de lansare aparține terminalului, în timp ce print("Salut") este cod Python. Închide sesiunea interactivă cu exit(), apoi execută comanda în terminal. Nu copia semnele de prompt din exemple în fișier.

Un editor poate avea terminalul integrat în aceeași fereastră. Asta nu schimbă distincția: zona în care editezi salut.py și zona în care lansezi programul au roluri diferite. Înainte de rulare salvează fișierul. Dacă modifici textul doar în editor și nu îl salvezi, interpretorul poate executa versiunea veche de pe disc, iar rezultatul pare să ignore schimbarea ta.

Instalarea și verificarea interpretorului

Folosește o versiune Python 3 întreținută, potrivită sistemului tău. Pentru Windows, documentația actuală descrie Python Install Manager, disponibil prin python.org sau Microsoft Store. Interfețele instalatoarelor mai vechi diferă, deci o instrucțiune despre o anumită bifă nu este universală. Pe macOS poți folosi distribuția oficială; pe Linux urmează instrucțiunile distribuției, inclusiv pachetul pentru venv dacă este separat. Nu înlocui manual interpretorul folosit de sistem.

În PowerShell verifică instalarea astfel. Comenzile sunt pentru terminal, fiecare pe propriul rând:

python --version
python -c "import sys; print(sys.executable)"

Pe Linux sau macOS, verificarea obișnuită folosește python3:

python3 --version
python3 -c "import sys; print(sys.executable)"

Prima comandă trebuie să afișeze o versiune Python 3. A doua arată calea executabilului efectiv. Notează ambele rezultate. Două terminale pot găsi instalări diferite, iar un editor poate avea propriul interpretor selectat. Calea este o dovadă mai bună decât presupunerea că orice buton numit Run folosește aceeași instalare.

Dacă primești un mesaj că programul nu este găsit, încă nu ai executat codul lecției: problema este lansarea interpretorului. Verifică instalarea și deschide un terminal nou după modificările de configurare. Dacă ai mai multe instalări, consultă instrucțiunile oficiale pentru alegerea versiunii. Nu continua să instalezi pachete la întâmplare; un pachet nu repară o comandă Python care nu pornește.

Un director pentru proiect și un mediu virtual

Creează un director nou, numit de exemplu laborator-python, într-un loc în care îți păstrezi proiectele. Deschide terminalul în acel director. Un mediu virtual separă pachetele proiectului de cele ale altor proiecte. Sursa rămâne în directorul proiectului, în afara .venv. Mediul se recreează când muți proiectul; nu îl trata ca pe o arhivă portabilă a aplicației.

În PowerShell creează mediul și verifică-l prin executabilul său:

python -m venv .venv
.\.venv\Scripts\python.exe --version
.\.venv\Scripts\python.exe -m pip --version

Pe Linux sau macOS folosește:

python3 -m venv .venv
./.venv/bin/python --version
./.venv/bin/python -m pip --version

Opțiunea -m cere interpretorului să ruleze un modul. venv creează mediul, iar pip este instrumentul pentru pachete. Invocarea prin interpretorul ales evită ambiguitatea unei comenzi pip independente. În această lecție nu instalăm niciun pachet: tot ce folosim aparține bibliotecii standard. Dacă venv nu poate fi creat, citește eroarea și rezolvă componenta lipsă pentru distribuția ta înainte de următorul pas.

Activarea mediului este opțională. Pentru PowerShell comanda este .\.venv\Scripts\Activate.ps1, iar pentru bash sau zsh este source .venv/bin/activate. Ea permite folosirea comenzii scurte python în sesiunea curentă. Dacă politica PowerShell blochează activarea, poți continua cu executabilul explicit de mai sus. Nu este necesar să modifici politica sistemului pentru acest laborator.

Primul fișier, primul rezultat

Creează salut.py lângă directorul .venv, nu în interiorul lui. Salvează fișierul în UTF-8 și verifică să nu se numească salut.py.txt. Scrie doar cele două linii de cod de mai jos:

nume = "Ana"
print(f"Salut, {nume}!")

În prima linie, numele nume este asociat cu textul Ana. Ghilimelele delimitează textul; ele nu fac parte din mesajul afișat. A doua linie apelează print. Litera f din fața șirului permite introducerea valorii dintre acolade în mesaj. Programul trebuie să afișeze Salut, Ana! și să se încheie.

Rulează în PowerShell .\.venv\Scripts\python.exe salut.py sau, în bash/zsh, ./.venv/bin/python salut.py. Schimbă apoi Ana în Ștefan, salvează și rulează din nou. Rezultatul așteptat este Salut, Ștefan! Această schimbare verifică simultan că editezi fișierul corect, că îl salvezi și că textul cu diacritice este păstrat. Un terminal configurat cu altă codificare poate necesita ajustări separate pentru afișare.

Nu porni prima dată fișierul prin dublu clic: fereastra se poate închide imediat după terminare și pierzi mesajul de eroare. Terminalul deja deschis păstrează rezultatul vizibil. Când programul merge, notează comanda exactă, directorul din care ai executat-o și mesajul obținut. Aceste trei informații fac experimentul repetabil pentru tine și pentru un coleg.

Directorul curent nu este întotdeauna directorul scriptului

Pentru a vedea această diferență, creează diagnostic.py cu următorul conținut. pathlib și sys sunt module din biblioteca standard; import le face disponibile programului.

from pathlib import Path
import sys

print("Interpretor:", sys.executable)
print("Director curent:", Path.cwd())
print("Fișier:", Path(__file__).resolve())
print("Mediu virtual:", sys.prefix != sys.base_prefix)

Rulează fișierul folosind executabilul din .venv. Ultima linie trebuie să afișeze True. Cele două căi pentru director și fișier răspund la întrebări diferite: unde a fost lansată comanda și unde este salvat programul. În lecția despre CSV, această diferență va explica de ce o cale relativă poate funcționa într-un terminal și poate eșua în altul.

Pentru un experiment controlat, copiază căile absolute afișate și lansează scriptul din alt director folosind aceste căi. În PowerShell, înaintea unei căi de executabil între ghilimele se folosește operatorul &. Nu schimba programul în același timp cu directorul: vrem să observăm o singură variabilă. Fișierul raportat rămâne același, iar directorul curent se schimbă.

De la text fix la o intrare explicită

Un salut fix este util pentru verificarea mediului, dar o unealtă trebuie să primească date. Pentru primul experiment interactiv creează intreaba.py. input afișează întrebarea și așteaptă o linie de text. strip elimină spațiile de la margini; nu schimbă spațiile dintre cuvintele unui nume.

nume = input("Cum te numești? ").strip()
if not nume:
    raise SystemExit("Introdu un nume nevid.")
print(f"Salut, {nume}!")

Rulează și introdu Ana Maria. Așteptarea este Salut, Ana Maria! Repetă cu numai spații: programul trebuie să se oprească prin mesajul de validare. Condiția if not nume verifică aici dacă textul rezultat este gol. Nu generaliza această regulă la orice câmp: în lecția următoare vom vedea că zero poate fi o valoare numerică perfect validă.

Observă indentarea de patru spații înainte de raise. Ea arată că oprirea aparține ramurii pentru intrare goală. Linia print revine la marginea stângă și se execută doar dacă programul nu s-a oprit. Dacă indentezi și print în ramura care tocmai oprește execuția, nu vei mai obține salutul dorit. Structura vizuală este parte din program, nu doar aranjarea lui.

O comandă utilă: planul de lectură

Pentru lucru repetabil, datele pot fi argumente ale comenzii, fără întrebări interactive. Construim plan.py: primește un nume și un număr de sesiuni, apoi calculează minutele planificate. Regula laboratorului este simplă: între una și zece sesiuni, fiecare de 25 de minute. Durata este o convenție pentru exercițiu, nu o recomandare medicală sau o măsură a productivității.

Folosim argparse pentru citirea argumentelor. Nu trebuie să construiești singur un parser pentru acest prim program. Citiți mai întâi codul integral, apoi urmăriți explicația de după el. Funcțiile proprii și modulele vor fi dezvoltate într-o lecție separată; aici păstrăm execuția liniară.

import argparse

parser = argparse.ArgumentParser(
    description="Planifică sesiuni de lectură de 25 minute."
)
parser.add_argument("nume")
parser.add_argument("--sesiuni", type=int, default=1)
args = parser.parse_args()

nume = args.nume.strip()
if not nume:
    parser.error("Numele trebuie să conțină text.")
if not 1 <= args.sesiuni <= 10:
    parser.error("Sesiunile trebuie să fie între 1 și 10.")

minute = args.sesiuni * 25
print(f"{nume}: {args.sesiuni} sesiuni, {minute} minute.")

Argumentul nume este obligatoriu. Opțiunea --sesiuni este opțională și are valoarea implicită 1. type=int cere conversia la întreg; un text precum trei este respins înaintea calculului. Conversia nu exprimă însă toată regula: și minus doi este întreg, dar nu este un număr de sesiuni acceptat. Din acest motiv verificăm separat intervalul.

După parse_args, args conține valorile interpretate. Normalizăm doar spațiile exterioare ale numelui și respingem rezultatul gol. Expresia 1 <= args.sesiuni <= 10 include ambele limite. Dacă toate condițiile sunt îndeplinite, înmulțirea produce minutele și print afișează o propoziție. Nu există scriere în fișiere și nu este trimisă nicio cerere de rețea.

Rulează în PowerShell .\.venv\Scripts\python.exe plan.py "Ana Maria" --sesiuni 3. În bash/zsh înlocuiește executabilul cu ./.venv/bin/python. Rezultatul exact este Ana Maria: 3 sesiuni, 75 minute. Ghilimelele fac ca cele două cuvinte să ajungă ca un singur argument. Fără ele, Maria este un argument suplimentar pe care parserul îl respinge.

Citește o eroare înainte să modifici programul

Există erori de lansare, erori de sintaxă și erori care apar în timpul execuției. Mesajul că un fișier nu poate fi deschis poate indica un director greșit sau o extensie greșită. SyntaxError indică o construcție pe care Python nu o poate interpreta. NameError poate apărea dacă folosești numee în loc de nume. Mesajul produs de parser pentru sesiuni invalide este, în schimb, un răspuns prevăzut pentru date neacceptate.

Când vezi un traceback, începe cu tipul și mesajul de la final, apoi caută fișierul și linia relevante din programul tău. Nu șterge toate verificările doar ca să dispară mesajul. Scrie ce intrare a provocat problema, ce ai așteptat și ce s-a întâmplat. Schimbă un singur lucru și repetă aceeași comandă. Astfel înveți cauza, în loc să obții întâmplător o versiune care pare să meargă.

Pentru plan.py, o încheiere normală are codul zero. O eroare de argument produsă de argparse are codul doi. În PowerShell verifici imediat $LASTEXITCODE, iar în bash/zsh verifici imediat echo $?. Cuvântul imediat contează: o altă comandă poate înlocui rezultatul pe care doreai să îl inspectezi. Mesajele de ajutor și de eroare au roluri diferite, chiar dacă ambele sunt text în terminal.

Laborator: demonstrează contractul comenzii

Înainte de testare, scrie pe hârtie rezultatele așteptate pentru cinci comenzi: Ana fără opțiuni, Ana cu trei sesiuni, Ana cu zece sesiuni, Ana cu zero sesiuni și Ana cu textul trei în locul numărului. Primele trei trebuie să reușească și să producă 25, 75 și 250 de minute. Ultimele două trebuie să fie respinse. Nu este suficient să verifici numai exemplul fericit cu valoarea trei.

Adaugă două verificări pentru nume: Ana Maria transmis într-un singur argument și un argument care conține numai spații. Primul trebuie păstrat integral, al doilea trebuie respins. Dacă ai omis ghilimelele, corectează comanda, nu programul. Eroarea aparține modului de lansare. Dacă ai eliminat strip și spațiile trec validarea, corectează programul și repetă cazul pentru a demonstra remedierea.

Cazul de la limită este deosebit de valoros. Valoarea zece trebuie acceptată, iar unsprezece trebuie respinsă. Dacă ai scris accidental < 10, zece eșuează și testul îți arată că implementarea diferă de regula formulată în cuvinte. Dacă ai verificat doar că numărul este pozitiv, unsprezece va trece. Aceeași disciplină va fi folosită pentru sume, stocuri și rânduri CSV.

Pentru exercițiul de modificare, schimbă convenția la 30 de minute pe sesiune. Predicția pentru trei sesiuni devine 90 de minute. Actualizează și descrierea parserului, nu doar înmulțirea, apoi verifică --help. Un program poate calcula corect și totuși să inducă utilizatorul în eroare dacă documentația lui afirmă altceva. Acest exercițiu verifică acordul dintre comportament și explicație.

Rezolvare orientativă și fișa de predare

Versiunea inițială a laboratorului folosește 25 de minute. Pentru modificare, cele două locuri care se schimbă sunt textul description și operandul 25 din calcul. Nu modifica limitele de la una la zece: enunțul nu a cerut acest lucru. Reexecută toate cazurile, inclusiv cele invalide; o schimbare a duratei nu trebuie să transforme zero sau unsprezece în intrări acceptate.

Într-un README.txt notează versiunea interpretorului, calea relativă a executabilului mediului, comanda de creare a mediului și trei comenzi de verificare. Include un rezultat de succes și unul de eșec, cu codurile observate. Menționează că programul nu necesită pachete externe. Păstrează sursele salut.py, diagnostic.py, intreaba.py și plan.py lângă acest document.

Ultima probă este să închizi terminalul și să reproduci rularea din instrucțiunile tale. Dacă ai folosit activarea fără să o documentezi, poți descoperi că python indică altă instalare. Folosirea căii explicite către interpretorul din .venv elimină această ambiguitate în laborator. Nu arhiva mediul în locul surselor: un coleg are nevoie de program și de pașii de recreare, nu de instalarea ta locală.

Ai terminat lecția când poți explica de ce programul acceptă trei sesiuni, de ce respinge zero, de ce Ana Maria trebuie transmis ca un argument și cum demonstrezi ce interpretor l-a executat. Aceste explicații sunt mai utile decât o captură cu un singur mesaj de succes. În următoarea lecție vom analiza ce înseamnă un număr, un text și o valoare booleană, astfel încât validarea să fie o decizie explicită.

Studiu de caz: terminalul merge, butonul editorului nu

Maria deschide plan.py în editor și îl rulează din terminal cu numele Ana și trei sesiuni. Obține rezultatul corect. Apasă apoi butonul Run, iar programul spune că lipsește numele. Prima ipoteză ar putea fi că editorul nu înțelege argparse, dar rezultatul arată altceva: editorul a lansat scriptul fără argumentul obligatoriu. Codul și parserul funcționează conform contractului.

Pentru diagnostic, Maria compară cele două lansări. În terminal poate vedea explicit numele fișierului, Ana și opțiunea --sesiuni 3. În configurația butonului există doar calea fișierului. Soluția este să configureze argumentele pentru rulare sau să folosească terminalul documentat în README. Nu adaugă un nume implicit în program doar ca să ascundă diferența: aceea ar fi o schimbare a cerinței, nu repararea lansării.

Un al doilea coleg obține mesajul vechi, deși a schimbat durata la 30. El verifică mai întâi dacă a salvat. Apoi rulează diagnostic.py și compară calea fișierului cu directorul deschis în editor. Descoperă două copii ale proiectului, una într-un director descărcat și alta în directorul de lucru. Comanda lui executa copia veche. Corectura constă în lansarea sursei potrivite și eliminarea ambiguității din notițe, nu în reinstalarea Python.

Aceste situații ilustrează o ordine utilă a verificărilor: confirmă comanda, fișierul salvat, calea executată și intrările, apoi investighează algoritmul. Un rezultat greșit poate proveni dintr-un program corect lansat în alt context. În registru, scrie cauza precisă și proba care a confirmat-o. Formularea „am reinstalat și acum merge” nu explică incidentul și nu ajută când aceeași problemă reapare.