# 11. Brief tour of the standard library — part II

În partea a doua a turului ne vom referi la module avansate care deservesc nevoile programatorului profesionist. Nu este de așteptat ca astfel de module să apară prea des în scripturile de dimensiuni mici.

## 11.1. Output formatting

Modulul `reprlib` ne pune la dispoziție o versiune a funcției `repr()` adaptată la afișările cu abrevieri de conținut atât pentru containere masive cât și pentru containerele cu imbricări multiple (stratificate):

    >>> import reprlib
    >>> reprlib.repr(set('pneumonoultramicroscopicsilicovolcaniconioza'))
    "{'a', 'c', 'e', 'i', 'l', 'm', ...}"

Modulul `pprint` oferă un control (încă și) mai sofisticat asupra afișării atât a obiectelor predefinite cât și a celor definite de utilizator, control care le face pe acestea lizibile pentru interpretor. În caz că rezultatul va depăși lungimea unui rând, „tipograful îngrijit” (sau realizatorul de aranjări sugestive; de la englezescul pretty printer) îi va adăuga caractere sfârșit-de-rând și indentări pentru a revela cu claritate structura datelor (ce trebuie afișate):

    >>> import pprint
    >>> paletă = [[[['negru', 'turcoaz'], 'alb', ['verde',
    ...           'roșu']], [['fucsia', 'galben'], 'albastru']]]
    ...
    >>> pprint.pprint(paletă, width=30)
    [[[['negru', 'turcoaz'],
       'alb',
       ['verde', 'roșu']],
      [['fucsia', 'galben'],
       'albastru']]]

Modulul `textwrap` formatează paragrafele de text pentru ca acestea să încapă pe un ecran (de terminal) cu lungimea dată:

    >>> import textwrap
    >>> documentul = """Metoda wrap() este la fel cu metoda fill() doar că returnează
    ... o listă de șiruri de caractere în locul unui șir de caractere foarte lung care
    ... conține caractere sfârșit-de-rând pentru a putea să delimiteze rândurile
    ... în care a fost împărțit."""
    ...
    >>> print(textwrap.fill(documentul, width=40))
    Metoda wrap() este la fel cu metoda
    fill() doar că returnează o listă de
    șiruri de caractere în locul unui șir de
    caractere foarte lung care conține
    caractere sfârșit-de-rând pentru a putea
    să delimiteze rândurile în care a fost
    împărțit.

Modulul `locale` accesează o bază de date (POSIX) cu formate de date specifice diverselor culturi. Atributul de grupare al funcției de format din (modulul) locale ne pune la îndemână o modalitate imediată de formatare a numerelor cu ajutorul separatoarelor de grup:

    >>> import locale
    >>> locale.setlocale(locale.LC_ALL, 'English_United States.1252')
    'English_United States.1252'
    >>> # Obțineți o mapare a convențiilor (obiceiurile locale):
    >>> convenții = locale.localeconv()
    >>> numărul = 1234567.8
    >>> locale.format_string("%d", numărul, grouping=True)
    '1,234,567'
    >>> locale.format_string("%s%.*f", (convenții['currency_symbol'],
    ...                      convenții['frac_digits'], numărul),
    ...                      grouping=True)
    '$1,234,567.80'

## 11.2. Folosirea șabloanelor

Modulul `string` include o clasă `Template` versatilă a cărei sintaxă simplificată o face ușor de întrebuințat de către utilizatori. Cu ajutorul său, aceștia pot să-și personalizeze aplicațiile fără a fi nevoiți să opereze modificări în codul de bază al respectivelor aplicații.

Formatul (din șablon) utilizează nume de înlocuire construite din identificatori valizi în Python (adică, alcătuiți doar din caractere alfanumerice și din caractere bară jos; atenție, doar caractere ASCII) pe care le prefațăm cu `$`. Numele de înlocuire se încadrează cu acolade, ceea ce le permite să fie urmate de (și mai multe) litere alfanumerice, însă acestea fără spații goale printre ele. Pentru escaparea unui caracter `$`, el va fi inserat sub forma `$$`:

    >>> from string import Template
    >>> șablonul = Template("Amice-din-orașul-${localitatea}City, "
    ...                     "dă și matale $$10 pe $visul_nostru.")
    >>> șablonul.substitute(localitatea='Medgidia',
    ...                     visul_nostru='apa gârlei')
    'Amice-din-orașul-MedgidiaCity, dă și matale $10 pe apa gârlei.'

Metoda `substitute()` ridică o excepție `KeyError` dacă vreun nume de înlocuire nu îi va fi furnizat fie de către un argument de tip dicționar de date fie de un argument cuvânt-cheie. În cazul unor aplicații cu documente construite în stilul Mail Merge (îmbinare-de-mesaje) survin situații când datele oferite de utilizator rămân incomplete, din care motiv utilizarea metodei `safe_substitute()` ar putea fi (mai) potrivită — căci aceasta nu va modifica numele de înlocuire dacă lipsesc datele corespunzătoare respectivelor nume. Exemplul de mai jos face referire la episodul cu rândunica (Monty Python):

    >>> șablonul = Template('De înapoiat $colet la $expeditor.')
    >>> dicționarul = dict(colet='rândunica fără nimica')
    >>> șablonul.substitute(dicționarul)
    Traceback (most recent call last):
      ...
    KeyError: 'expeditor'
    >>> șablonul.safe_substitute(dicționarul)
    'De înapoiat rândunica fără nimica la $expeditor.'

Urmașele clasei Template își pot personaliza delimitatorul. De exemplu, un script utilitar de redenumire a unor loturi de fotografii, atașat unui album fotografic, poate întrebuința semnul grafic procent pe post de caracter de înlocuire pentru șiruri de caractere precum data calendaristică, numărul (de ordine în lot al) fișierului foto, respectiv extensia fișierului:

    >>> import string, time, os.path
    >>> fișiere_foto = ['img_1074.jpg', 'img_1076.jpg', 'img_1077.jpg']
    >>> class RedenumeșteLotul(string.Template):
    ...     delimiter = '%' # suprascriem atributul delimiter
    ...
    >>> formatul = input("Introduceți stilul redenumirii "
    ...                  "(%d-data %n-numărul %f-extensia_fișierului):  ")
    Introduceți stilul redenumirii (%d-data %n-numărul %f-extensia_fișierului):  Viorica_%n%f

    >>> șablonul = RedenumeșteLotul(formatul)
    >>> data = time.strftime('%d%b%y')
    >>> for i, nume_de_fișier in enumerate(fișiere_foto):
    ...     baza, extensia = os.path.splitext(nume_de_fișier)
    ...     noul_nume = șablonul.substitute(d=data, n=i, f=extensia)
    ...     print('{0} --> {1}'.format(nume_de_fișier, noul_nume))

    img_1074.jpg --> Viorica_0.jpg
    img_1076.jpg --> Viorica_1.jpg
    img_1077.jpg --> Viorica_2.jpg

Ceea ce face șabloanele atât de utile în practică este chiar caracteristica esențială a acestora, și anume separarea logicii unui program de afișarea rezultatelor execuției lui. Astfel, pot fi construite șabloane personalizate pentru introducerea convenabilă a acestor rezultate în fișiere XML, în rapoarte sub formă de text simplu, ori în rapoarte HTML destinate Internetului.

## 11.3. Working with binary data record layouts

Modulul `struct` ne pune la dispoziție funcțiile `pack()` și `unpack()` pentru a putea manipula formate de înregistrări binare de lungimi diverse. Exemplul de mai jos ne arată cum putem parcurge informația din antetul unui fișier ZIP fără a face uz de modulul `zipfile`. Codurile de arhivare (de la englezescul pack) `"H"` și `"I"` reprezintă numere întregi fără semn (cu lungime) de doi și respectiv de patru octeți. Semnul `"<"` ne arată că datele au lungime standard și sunt dispuse în formatul de stocare inversat (sau de memorare inversată; de la englezescul, ca jargon informatic, little-endian):

    >>> import struct
    >>> # Fișierul fișierul_meu.zip este arhiva ZIP a (minim) 3 fișiere text:
    >>> with open('fișierul_meu.zip', 'rb') as f:
    ...    datele = f.read()
    ...
    >>> început = 0
    >>> for i in range(3):                # afișează primele 3 antete
    ...                                   # de fișier
    ...    început += 14
    ...    câmpuri = struct.unpack('<IIIHH', datele[început:început+16])
    ...    crc32 \
    ...    ,mărime_comprimate \
    ...    ,mărime_necomprimate \
    ...    ,mărime_numedefișier \
    ...    ,mărime_suplimentar = câmpuri
    ...    început += 16
    ...    numedefișier = datele[început:început+mărime_numedefișier]
    ...    început += mărime_numedefișier
    ...    suplimentar = datele[început:început+mărime_suplimentar]
    ...    print(numedefișier \
    ...          ,hex(crc32) \
    ...          ,mărime_comprimate \
    ...          ,mărime_necomprimate)
    ...    început += mărime_suplimentar \
    ...             + mărime_necomprimate # trecem la antetul următor

## 11.4. Execuții multifilare

Execuția pe mai multe fire (sau multifir ori multifilară; de la englezescul threading) a unui program este o tehnică de organizare a execuției acestuia prin care se decuplează sarcinile (sau subunitățile; de la englezescul task) programului care nu depind (în mod direct) una de cealaltă. Firele de execuție (numite și procese de categorie ușoară) pot fi întrebuințate pentru a îmbunătăți receptivitatea unei aplicații la acțiunile utilizatorului său în timp ce execuția sarcinilor de durată se desfășoară în fundal (asincron). Un caz de utilizare relevant este cel al rulării (îndeplinirii) unor sarcini I/E (mai lente, de obicei) în paralel cu realizarea de sarcini de calcul, acestea din urmă fiind efectuate în alt fir de execuție.

Fragmentul de cod care urmează ne arată cum poate modulul de nivel înalt `threading` să execute sarcini în fundal pe când programul principal rulează (în prim-plan):

    import threading, zipfile

    class AsyncZip(threading.Thread):
        def __init__(self, infile, outfile):
            super().__init__()
            self.infile = infile
            self.outfile = outfile

        def run(self):
            with zipfile.ZipFile(self.outfile, 'w', zipfile.ZIP_DEFLATED) as f:
                f.write(self.infile)
            print('Finished background zip of:', self.infile)

    background = AsyncZip('mydata.txt', 'myarchive.zip')
    background.start()
    print('The main program continues to run in foreground.')

    background.join()    # Wait for the background task to finish
    print('Main program waited until background was done.')

Dificultatea principală a aplicațiilor multifir (adică, a aplicațiilor cu execuție pe mai multe fire) este cea a coordonării acestor fire de execuție vizavi de accesul la date ori la alte resurse (memorie, șamd.). În acest scop, modulul threading ne furnizează un număr de primitive de sincronizare, precum blocări (sau zăvoare; de la englezescul lock), evenimente, variabile de control și semafoare.

Chiar dacă aceste unelte sunt puternice, erorile de proiectare (fie și) minore ne pot pune în fața unor complicații dificil de reprodus (în mod sistematic). Din acest motiv, abordarea preferată în practică în ceea ce privește coordonarea sarcinilor este să realizăm (toată) accesarea resurselor într-un singur fir de execuție și să utilizăm modulul `queue` pentru a hrăni acest fir cu cereri din partea celorlalte fire de execuție. Aplicațiile care întrebuințează obiecte `Queue` pentru comunicarea între fire (sau comunicarea interprocese) și pentru coordonarea acestora sunt (mai) ușor de proiectat, (mai) stabile și au codul-sursă (mai) facil de citit.

## 11.5. Jurnalizarea

Modulul `logging` ne pune la dispoziție un sistem de jurnalizare flexibil și complet accesorizat. Folosite în modul cel mai simplu cu putință, mesajele de (introdus în) jurnal îi sunt transmise fie unui fișier (prestabilit) fie (fluxului) `sys.stderr`:

    import logging
    logging.debug('Informații de depanare')
    logging.info('Mesaj de informare')
    logging.warning('Avertisment: fișierul de configurare %s negăsit', 'serverul.conf')
    logging.error('Eroare survenită')
    logging.critical('Eroare critică -- opresc sistemul')

Iată ce se va afișa:

    WARNING:root:Avertisment: fișierul de configurare serverul.conf negăsit
    ERROR:root:Eroare survenită
    CRITICAL:root:Eroare critică -- opresc sistemul

În mod prestabilit, atât mesajele informative cât și cele de depanare sunt suprimate (de la jurnalizare) în timp ce ieșirea (conținutul) lor se trimite către fluxul standard de eroare. Alte opțiuni de ieșire includ distribuirea (sau rutarea; de la englezescul, ca jargon informatic, routing) mesajelor prin poșta electronică, datagrame, socluri, ori către un server HTTP. Filtre suplimentare permit alegerea unor distribuiri bazate pe prioritatea mesajelor: `DEBUG`, `INFO`, `WARNING`, `ERROR`, precum și `CRITICAL`.

Sistemul de jurnalizare se poate configura atât direct din Python cât și indirect, prin încărcarea setărilor dintr-un fișier de configurare care poate fi editat de către utilizator, permițându-se astfel jurnalizări personalizate a căror introducere să nu necesite modificarea codului-sursă de bază al aplicației.

## 11.6. Weak references

Python-ul își administrează memoria în mod automat (realizând atât contorizarea referințelor pentru majoritatea obiectelor cât și colectarea gunoiului pentru eliminarea circularităților). Orice zonă de memorie (rezervată) va fi eliberată la puțin timp după ce a fost eliminată (și) ultima referință la ea.

O atare abordare funcționează mulțumitor pentru cele mai multe dintre aplicații, însă câteodată este nevoie ca urmărirea anumitor obiecte să fie realizată doar atâta vreme cât ceva anume (din sistem) le întrebuințează. Din păcate, simpla urmărire a unui obiect creează o referință la acesta, care referință îl va face permanent (nemuritor). Modulul `weakref` conține unelte pentru urmărirea unor obiecte fără să se creeze nicio referință la ele. Atunci când un obiect anume nu mai este folosit, el va fi eliminat automat dintr-o tabelă de referințe slabe (de la englezescul, ca jargon informatic, weakref) și o rutină de răspuns (sau un apel de răspuns; de la englezescul, ca jargon informatic, callback) va fi declanșată pentru respectivul obiect weakref. Întrebuințările tipice ale referințelor slabe includ memorarea locală rapidă (de la englezescul, ca jargon informatic, caching) a obiectelor care sunt costisitor de creat:

    >>> import weakref, gc
    >>> class A:
    ...     def __init__(self, value):
    ...         self.value = value
    ...     def __repr__(self):
    ...         return str(self.value)
    ...
    >>> a = A(10)                   # create a reference
    >>> d = weakref.WeakValueDictionary()
    >>> d['primary'] = a            # does not create a reference
    >>> d['primary']                # fetch the object if it is still alive
    10
    >>> del a                       # remove the one reference
    >>> gc.collect()                # run garbage collection right away
    0
    >>> d['primary']                # entry was automatically removed
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
        d['primary']                # entry was automatically removed
      File "C:/python315/lib/weakref.py", line 46, in __getitem__
        o = self.data[key]()
    KeyError: 'primary'

## 11.7. Tools for working with lists

Multe din cerințele unor structuri (abstracte) de date pot fi deservite de tipul predefinit (de date) listă. Cu toate acestea, în anumite situații este nevoie de implementări alternative ale unei structuri de date, punându-se în balanță, la alegerea lor, performanțe specifice.

Modulul `array` dispune de obiectul `array` (adică, tipul tablou, vector ori matrice) care îi seamănă listei, doar că nu poate stoca decât date de același tip (omogene) iar stocarea propriu-zisă se face (mai) compact. Exemplul de mai jos prezintă un tablou de numere întregi stocate sub formă de numere binare fără semn (lungi) de câte doi octeți (și având codul de tip `"H"`), aceasta spre deosebire de cazul listelor Python uzuale formate din obiecte int, în care fiecare item este stocat pe câte 16 octeți:

    >>> from array import array
    >>> tablou = array('H', [4000, 10, 700, 22222])
    >>> sum(tablou)
    26932
    >>> tablou[1:3]
    array('H', [10, 700])

Modulul `collections` ne furnizează obiectul `deque` (adică, tipul deque ori coadă cu două capete) care îi seamănă listei, doar că acceptă (de la englezescul append) și elimină (de la englezescul pop) itemi la și de la capete mai repede decât o poate face o listă, respectiv caută itemi (de la englezescul lookup) mai încet decât poate o listă atunci când itemii respectivi se găsesc în interiorul (mijlocul) său. Instanțele acestui tip sunt cum nu se poate mai potrivite pentru implementarea de cozi (FIFO, LIFO), respectiv de căutări în lățime (a unor itemi) în diverși arbori de date:

    >>> from collections import deque
    >>> coada_cu_două_capete = deque(["sarcina1", "sarcina2", \
    ...                               "sarcina3"])
    >>> coada_cu_două_capete.append("sarcina4")
    >>> print("Mă ocup de ", coada_cu_două_capete.popleft())
    Mă ocup de sarcina1

    unde_caut = deque([nodul_de_început])
    def căutare_în_lățime(unde_caut):     # căutare breadth-first
        nodul = unde_caut.popleft()
        for c in ce_mi_am_propus(nodul):
            if este_țelul_meu(c):
                return c
            unde_caut.append(c)

În plus față de implementările alternative ale listei, biblioteca ne pune la dispoziție și altfel de unelte, precum cele din modulul `bisect` care conține funcții pentru manipularea listelor (deja) sortate:

    >>> import bisect
    >>> scoruri = [(100, 'Perl'), (200, 'Tcl'), (400, 'Lua'), (500, 'Python')]
    >>> bisect.insort(scoruri, (300, 'Ruby'))
    >>> scoruri
    [(100, 'Perl'), (200, 'Tcl'), (300, 'Ruby'), (400, 'Lua'), (500, 'Python')]

Modulul `heapq` deține funcții pentru implementarea structurilor arborescente heap (adică, generic, grămadă; se utilizează de multe ori, în mod superficial, și expresia coadă cu priorități) folosind lista obișnuită. Itemul cu cea mai mică valoare este păstrat întotdeauna în poziția zero. Această caracteristică a structurilor heap le face să fie de folos pentru aplicațiile în care accesăm în mod frecvent elementul cu cea mai mică valoare (dintr-o listă de valori) dar nu dorim să realizăm o sortare completă a listei:

    >>> from heapq import heapify, heappop, heappush
    >>> datele = [1, 3, 5, 7, 9, 2, 4, 6, 8, 0]
    >>> # reorganizăm lista pentru a avea o ordonare de heap:
    >>> heapify(datele)
    >>> heappush(datele, -5)               # introducem un item
    >>> # extragem cele mai mici trei valori:
    >>> [heappop(datele) for i in range(3)]
    [-5, 0, 1]

## 11.8. Decimal floating-point arithmetic

Modulul `decimal` ne oferă tipul de date `Decimal`, dedicat aritmeticii zecimale în virgulă mobilă. Prin comparație cu implementarea predefinită `float` a numerelor binare în virgulă mobilă, clasa de față este realmente utilă pentru

- aplicațiile financiare ori alte aplicații în care se cer reprezentări exacte în baza zece ale datelor numerice,

- situațiile în care controlul (numerelor) este mai important decât precizia (cifrelor din dreapta virgulei),

- cazurile când rotunjirea valorilor numerice trebuie să țină seama de cerințe legale sau de alte reglementări specifice,

- monitorizea cifrelor zecimale semnificative din dreapta punctului (virgulei), respectiv pentru

- aplicațiile la care utilizatorul se așteaptă ca rezultatele diverselor operații să se potrivească cu cele obținute chiar de el în urma calculelor făcute cu creionul pe hârtie.

Cu titlu de exemplu, calculul unei taxe de 5% la valoarea de 70 de cenți a unei facturi de convorbiri telefonice produce un rezultat diferit, atunci când este efectuat în virgulă mobilă binară, de rezultatul obținut în virgulă mobilă zecimală. Iar diferența nu mai poate fi trecută cu vederea dacă rotunjim rezultatele până la obținerea celui mai apropiat cent:

    >>> from decimal import *
    >>> round(Decimal('0.70') * Decimal('1.05'), 2)
    Decimal('0.74')
    >>> round(.70 * 1.05, 2)
    0.73

Rezultatul `Decimal` păstrează zerouri pe post de sufix, presupunând în mod automat că, în urma multiplicării unor operanzi cu câte două cifre semnificative la dreapta punctului, el va avea patru cifre semnificative după punct. Clasa Decimal reproduce matematica făcută cu creionul pe hârtie și evită, astfel, complicații care pot surveni atunci când anumite cantități zecimale nu sunt reprezentabile exact cu valori binare în virgulă mobilă.

Întrebuințarea de reprezentări exacte îi permite clasei `Decimal` să realizeze atât împărțiri cu rest (calcule cu operatorul modulo) cât și testări de egalități care nu sunt realizabile cu numere binare în virgulă mobilă:

    >>> Decimal('1.00') % Decimal('.10')
    Decimal('0.00')
    >>> 1.00 % 0.10
    0.09999999999999995

    >>> sum([Decimal('0.1')]*10) == Decimal('1.0')
    True
    >>> 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 + 0.1 == 1.0
    False

În modulul `decimal`, aritmetica poate fi efectuată cu precizia stabilită de către utilizator:

    >>> getcontext().prec = 36
    >>> Decimal(1) / Decimal(7)
    Decimal('0.142857142857142857142857142857142857')