# 6. Module

Dacă, atunci când lucrați în terminal, părăsiți interpretorul Python-ului, veți constata, la revenirea la promptul interpretorului, că toate definițiile scrise în linia de comandă (fie ele definiții de funcții ori de variabile) s-au pierdut. Din acest motiv, atunci când vă pregătiți să scrieți un program mai lung de câteva linii de cod, ar fi mai bine să folosiți un editor de text pentru prepararea acestui program și apoi să rulați programul folosind fișierul în cauză pe post de date de intrare în interpretor. O asemenea întreprindere este numită creare de script. Pe măsură ce programul dumneavoastră se lungește, veți dori să-l împărțiți în mai multe fișiere pentru a-l întreține mai ușor. De asemeni, veți ajunge în situația de a dori să întrebuințați o funcție bine scrisă chiar de dumneavoastră în cadrul unor programe diverse fără să-i copiați, de fiecare dată, codul în vreunul din programele respective.

Pentru a vă ajuta în această privință, Python-ul dispune de o modalitate de a introduce definiții într-un fișier și apoi de a le utiliza fie într-un script fie într-o instanță interactivă a interpretorului. Un astfel de fișier este numit modul; definițiile dintr-un modul pot fi importate atât în alte module cât și în modulul main (modulul principal, adică acea colecție de variabile la care aveți acces dintr-un script executat la nivelul cel mai înalt precum și atunci când lucrați în modul calculator – bucla REPL).

Modulul constituie, așadar, un fișier conținând definiții și instrucțiuni scrise în Python. Numele fișierului este numele modulului la care adăugăm sufixul `.py`. În interiorul (codului Python al) unui modul, numele modulului (sub forma unui șir de caractere) ne va fi accesibil ca valoare a variabilei globale `__name__`. Ca să vedem aceasta, vă rugăm să întrebuințați editorul dumneavoastră favorit de text pentru a crea fișierul cu numele `fibo.py`, situat în directorul curent și având următorul conținut:

    # Fibonacci numbers module

    def fib(n):    # write Fibonacci series up to n
        a, b = 0, 1
        while a < n:
            print(a, end=' ')
            a, b = b, a+b
        print()

    def fib2(n):   # return Fibonacci series up to n
        result = []
        a, b = 0, 1
        while a < n:
            result.append(a)
            a, b = b, a+b
        return result

Apoi, porniți interpretorul de Python și importați modulul tocmai scris cu comanda care urmează:

    >>> import fibo

Execuția comenzii nu va adăuga numele funcțiilor definite în `fibo` direct la spațiul de nume curent (vezi Domenii de valabilitate și spații de nume în Python pentru mai multe detalii); tot ce va face va fi să adauge numele `fibo` spațiului de nume respectiv. Apelând la numele modulului, veți putea accesa funcțiile acestuia:

    >>> fibo.fib(1000)
    0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
    >>> fibo.fib2(100)
    [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
    >>> fibo.__name__
    'fibo'

Dacă intenționați să folosiți o anumită funcție în mod frecvent, atunci îi puteți atribui unei variabile locale numele acesteia:

    >>> fib = fibo.fib
    >>> fib(500)
    0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

## 6.1. Mai multe despre module

Orice modul poate conține atât instrucțiuni executabile cât și definiții de funcții. Aceste instrucțiuni sunt folosite la inițializarea modulului. Adică, ele vor fi executate doar prima dată când numele modulului în cauză va fi întâlnit de către interpretor într-o instrucțiune de import. [1] (Instrucțiunile vor fi rulate și atunci când fișierul – modulul – va fi executat ca script.)

Fiecare modul are propriul său spațiu de nume privat, care va fi utilizat ca spațiu de nume global de către toate funcțiile definite în modulul respectiv. Astfel, autorul unui modul poate întrebuința variabile globale în codul Python al modulului fără să se teamă de eventualele conflicte de nume dintre aceste variabile și variabilele globale ale utilizatorului (modulului). Pe de altă parte, dacă sunteți siguri pe ceea ce faceți, atunci veți putea întrebuința variabilele globale ale unui modul cu aceeași notație pe care o utilizați pentru a vă referi la funcțiile modulului, și anume `nume_de_modul.nume_de_item`.

Modulele pot importa alte module. Se obișnuiește, fără a fi obligatoriu, să plasăm toate instrucțiunile `import` la începutul oricărui modul (respectiv, al oricărui script). Numele de module importate, dacă sunt poziționate la nivelul cel mai de sus al modulului (adică, în exteriorul oricărui cod de funcție sau de clasă din modul), vor fi adăugate spațiului de nume global al modulului.

Există o variantă a instrucțiunii `import` care realizează importurile de nume dintr-un modul direct în spațiul de nume al modulului importator. Iată un exemplu de folosire a ei:

    >>> from fibo import fib, fib2
    >>> fib(500)
    0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Varianta nu va introduce numele modulului din care facem importurile în spațiul de nume local (așa că, în exemplul anterior, `fibo` nu este definit).

Dispunem chiar și de o modalitate de a importa toate numele pe care le definește un modul:

    >>> from fibo import *
    >>> fib(500)
    0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Această variantă a instrucțiunii despre care discutăm va importa toate numele cu excepția celor care încep cu o bară jos (`_`). De cele mai multe ori, programatorii de Python nu vor apela la această facilitate a limbajului deoarece ea va introduce un set necunoscut de nume în spațiul de nume folosit de interpretor, putând astfel masca o serie de chestiuni deja definite de dumneavoastră.

Să remarcăm, așadar, că obiceiul de a importa `*` fie dintr-un modul fie dintr-un pachet este descurajat de profesioniști, dat fiind că el cauzează, în majoritatea situațiilor, apariția unui cod greu de citit. Cu toate acestea, este permis să îl practicați în sesiunile interactive de lucru cu interpretorul de Python, ca să aveți mai puțin de tastat.

Dacă numele unui modul este urmat de `as`, atunci numele situat la dreapta lui `as` va fi legat direct de modulul importat.

    >>> import fibo as fib
    >>> fib.fib(500)
    0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Procedând astfel, importul modulului se va realiza la fel ca în urma execuției instrucțiunii `import fibo`, singura deosebire fiind aceea că modulul va fi disponibil sub numele (modificat convenabil) de `fib`.

Efecte similare vor fi obținute dacă procedăm în acest mod și atunci când folosim versiunea cu `from` a instrucțiunii de import:

    >>> from fibo import fib as fibonacci
    >>> fibonacci(500)
    0 1 1 2 3 5 8 13 21 34 55 89 144 233 377

Notă

Din rațiuni de eficiență, orice modul va fi importat o singură dată într-o sesiune de lucru cu interpretorul. Așa că, dacă îi aduceți modificări modulului, va trebui să reporniți interpretorul – ori, dacă este vorba doar despre un singur modul ce trebuie testat interactiv, folosiți `importlib.reload()`, precum, de exemplu, în `import importlib; importlib.reload(numele_modulului)`.

### 6.1.1. Executând module ca scripturi

Atunci când rulați un modul Python cu

    python fibo.py <arguments>

codul modulului va fi executat ca și cum modulul ar fi fost importat, cu excepția faptului că variabila `__name__` va fi setată ca `"__main__"`. Ceea ce înseamnă că, dacă ați adăuga următoarele linii de cod la sfârșitul modulului dumneavoastră:

    if __name__ == "__main__":
        import sys
        fib(int(sys.argv[1]))

atunci ați face fișierul (modulului) utilizabil atât ca script cât și ca modul importabil doarece codul în care se parsează conținutul liniei de comandă va rula numai atunci când modulul se execută ca fișier „main”:

    $ python fibo.py 50
    0 1 1 2 3 5 8 13 21 34

În schimb, atunci când modulul este importat, codul nu va fi rulat:

    >>> import fibo
    >>>

Acest procedeu este frecvent întrebuințat fie pentru a-i adăuga modulului o interfață cu utilizatorul convenabilă fie în scop de testare (atunci când, la rularea modulului ca script, va fi executată o suită de teste).

### 6.1.2. Calea de căutare a modulelor

Atunci când un modul numit `cutare` este importat, interpretorul va începe prin a căuta un modul predefinit cu același nume. Numele acestor module sunt înșiruite în tuplul `sys.builtin_module_names`. Dacă nu îl găsește, atunci interpretorul va căuta un fișier intitulat `cutare.py` într-o listă de directoare furnizată de variabila `sys.path`. `sys.path` este inițializată cu una din următoarele locații:

- Directorul care conține scriptul folosit ca dată de intrare la interpretor (sau directorul curent dacă nu a fost precizat niciun fișier).

- `PYTHONPATH` (o listă cu nume de directoare, având aceeași sintaxă ca variabila interpretorului de comenzi – de la englezescul shell – `PATH`).

- Locația implicită, depinzând de modalitatea de instalare (incluzând, în mod convențional, un director `site-packages`, manipulată de modulul `site`).

Mai multe detalii se găsesc în Inițializarea căii de acces din modulul sys.path.

Notă

În sistemele de fișiere care suportă legături slabe (în englezește, ca jargon, symlink), directorul care conține scriptul de intrare va fi calculat numai după ce este urmată legătura. Cu alte cuvinte, directorul care conține legătura slabă nu îi va fi adăugat căii de căutare a modulelor.

Odată inițializate, programele Python pot modifica `sys.path`-ul. Directorul care conține scriptul ce este rulat va fi plasat la începutul căii de căutare, înaintea căii bibliotecii standard. Ceea ce înseamnă că scripturile din directorul în cauză vor fi încărcate în locul modulelor cu același nume din directorul bibliotecii standard. Dacă aceasta nu este intenția dumneavoastră, atunci situația constituie o eroare serioasă. A se vedea Module standard pentru mai multe informații.

### 6.1.3. Fișiere Python „compilate”

Pentru a accelera încărcarea modulelor, Python-ul salvează în directorul de cache `__pycache__` versiuni compilate ale tuturor modulelor, cu numele `modulul.versiunea.pyc`, în care versiunea conține codificarea formatului pentru fișierul compilat; în general, ea include numărul de versiune al Python-ului. De exemplu, în ediția (de la englezescul release) 3.3 a CPython-ului, varianta compilată a lui cutare.py ar fi salvată drept `__pycache__/cutare.cpython-33.pyc`. O atare convenție de nume le permite modulelor compilate ale diverselor ediții și diferitelor versiuni ale Python-ului să coexiste.

Python-ul compară data modificării fișierelor-sursă cu cea a versiunilor compilate pentru a stabili dacă acestea din urmă sunt depășite cronologic și este nevoie să fie recompilate. Procesul de comparare și recompilare este complet automatizat. În plus, modulele compilate sunt independente de platforma de calcul, astfel că aceeași bibliotecă poate fi partajată (de la englezescul shared) cu sisteme de arhitecturi diferite.

Python-ul nu verifică zona de cache în două circumstanțe. În prima, pentru că el recompilează de fiecare dată, fără a stoca rezultatul recompilării în directorul de cache, modulul care se încarcă din linia de comandă. În cea de-a doua situație, el nu verifică zona de cache atunci când modulul nu dispune de fișier-sursă. Pentru ca Python-ul să suporte o distribuție fără cod-sursă (adică una doar compilată), modulul compilat trebuie să fie localizat în directorul-sursă și nu trebuie să existe în distribuție niciun fișier-sursă al modulului în cauză.

Ponturi pentru experți:

- Puteți întrebuința opțiunile `-O` sau `-OO` ale unei comenzi Python pentru a reduce mărimea unui modul compilat. Opțiunea `-O` elimină instrucțiunile de aserțiune (de la englezescul assert), iar opțiunea `-OO` elimină atât instrucțiunile de aserțiune cât și șirurile __doc__. Dat fiind că anumite programe se bazează pe existența acestora, ar trebui să utilizați această opțiune numai atunci când sunteți sigur pe ceea ce faceți. Modulele „optimizate” au eticheta `opt-` și sunt, de obicei, mai mici (decât originalele). Edițiile viitoare ale Python-ului pot modifica efectele acestor optimizări.

- Niciun program nu va rula mai repede atunci când este citit dintr-un fișier `.pyc` decât atunci când este citit dintr-un fișier `.py`; tot ceea ce este mai rapid în privința fișierelor `.pyc` este viteza cu care sunt încărcate.

- Modulul `compileall` le poate crea fișiere .pyc tuturor modulelor dintr-un director.

- Mult mai multe detalii despre acest proces al compilării modulelor, inclusiv un arbore de decizie util, se găsesc în PEP 3147.

## 6.2. Module standard

Python-ul vine însoțit de o bibliotecă de module standard, descrisă într-un document separat, Referința bibliotecii Python (denumit „Referința bibliotecii” de aici înainte). Anumite module sunt construite ca parte a interpretorului; ele oferă acces la operații care nu fac parte din corpul (de la englezescul core) limbajului dar sunt, cu toate acestea, incluse în el, fie din rațiuni de eficiență fie pentru a-i da acces utilizatorului la primitive ale sistemului de operare precum apelurile (de) sistem. Setul acestor module este accesibil printr-o opțiune de configurare care depinde, la rândul ei, de platforma de calcul folosită. De exemplu, modulul `winreg` va fi disponibil numai pe sistemele de calcul cu Windows. Un modul particular merită atenția dumneavoastră: `sys`, el fiind construit ca parte a oricărui interpretor de Python. Variabilele `sys.ps1` și `sys.ps2` au drept valori șirurile de caractere folosite pe post de promptul primar, respectiv de promptul secundar:

    >>> import sys
    >>> sys.ps1
    '>>> '
    >>> sys.ps2
    '... '
    >>> sys.ps1 = 'C> '
    C> print('Yuck!')
    Yuck!
    C>

Aceste două variabile sunt definite doar dacă interpretorul lucrează în modul interactiv.

Variabila `sys.path` este o listă formată din șiruri de caractere care determină calea de căutare a modulelor. Este inițializată cu o cale de acces implicită preluată din variabila de mediu `PYTHONPATH`, ori dintr-o altă cale de acces prestabilită atunci când `PYTHONPATH` nu a fost setată. O puteți modifica folosind operațiile tipice cu liste:

    >>> import sys
    >>> sys.path.append('/ufs/guido/lib/python')

## 6.3. Funcția `dir()`

Funcția predefinită `dir()` este întrebuințată la aflarea numelor pe care le definește un anumit modul. Ea returnează o listă sortată de șiruri de caractere:

    >>> import fibo, sys
    >>> dir(fibo)
    ['__name__', 'fib', 'fib2']
    >>> dir(sys)
    ['__breakpointhook__', '__displayhook__', '__doc__', '__excepthook__',
     '__interactivehook__', '__loader__', '__name__', '__package__', '__spec__',
     '__stderr__', '__stdin__', '__stdout__', '__unraisablehook__',
     '_clear_type_cache', '_current_frames', '_debugmallocstats', '_framework',
     '_getframe', '_git', '_home', '_xoptions', 'abiflags', 'addaudithook',
     'api_version', 'argv', 'audit', 'base_exec_prefix', 'base_prefix',
     'breakpointhook', 'builtin_module_names', 'byteorder', 'call_tracing',
     'callstats', 'copyright', 'displayhook', 'dont_write_bytecode', 'exc_info',
     'excepthook', 'exec_prefix', 'executable', 'exit', 'flags', 'float_info',
     'float_repr_style', 'get_asyncgen_hooks', 'get_coroutine_origin_tracking_depth',
     'getallocatedblocks', 'getdefaultencoding', 'getdlopenflags',
     'getfilesystemencodeerrors', 'getfilesystemencoding', 'getprofile',
     'getrecursionlimit', 'getrefcount', 'getsizeof', 'getswitchinterval',
     'gettrace', 'hash_info', 'hexversion', 'implementation', 'int_info',
     'intern', 'is_finalizing', 'last_traceback', 'last_type', 'last_value',
     'maxsize', 'maxunicode', 'meta_path', 'modules', 'path', 'path_hooks',
     'path_importer_cache', 'platform', 'prefix', 'ps1', 'ps2', 'pycache_prefix',
     'set_asyncgen_hooks', 'set_coroutine_origin_tracking_depth', 'setdlopenflags',
     'setprofile', 'setrecursionlimit', 'setswitchinterval', 'settrace', 'stderr',
     'stdin', 'stdout', 'thread_info', 'unraisablehook', 'version', 'version_info',
     'warnoptions']

Utilizată fără argumente, `dir()` va lista numele definite în sesiunea curentă:

    >>> a = [1, 2, 3, 4, 5]
    >>> import fibo
    >>> fib = fibo.fib
    >>> dir()
    ['__builtins__', '__name__', 'a', 'fib', 'fibo', 'sys']

Remarcați faptul că ea listează toate tipurile de nume: pe cele de variabile, pe cele de module, de funcții șamd.

`dir()` nu listează nici numele funcțiilor predefinite (în englezește, ca jargon, built-in) și nici pe cele ale variabilelor predefinite. Dacă vă interesează lista acestora, atunci aflați că ele sunt definite în modulul standard `builtins`:

    >>> import builtins
    >>> dir(builtins)
    ['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',
     'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning',
     'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError',
     'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning',
     'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',
     'FileExistsError', 'FileNotFoundError', 'FloatingPointError',
     'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError',
     'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError',
     'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError',
     'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented',
     'NotImplementedError', 'OSError', 'OverflowError',
     'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError',
     'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning',
     'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',
     'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError',
     'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError',
     'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning',
     'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__',
     '__debug__', '__doc__', '__import__', '__name__', '__package__', 'abs',
     'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'callable',
     'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits',
     'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec', 'exit',
     'filter', 'float', 'format', 'frozenset', 'getattr', 'globals', 'hasattr',
     'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass',
     'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memoryview',
     'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property',
     'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice',
     'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars',
     'zip']

## 6.4. Pachete

Pachetele constituie o modalitate de structurare a spațiului de nume al modulelor Python folosind „nume-cu-puncte de module” (de la englezescul dotted). De exemplu, numele de modul `A.B` se referă la (sub)modulul `B` din pachetul numit `A`. Tot așa cum utilizarea modulelor îl scapă pe autorul unui modul de grija eventualelor conflicte de nume cu variabilele globale din modulul altui autor, întrebuințarea de nume-cu-puncte de module îi scapă pe autorii unor pachete multi-modul precum NumPy sau Pillow de grija numelor de module ale altor autori de pachete multi-modul.

Să presupunem că doriți să proiectați o colecție de module (adică, un „pachet”) dedicate manipulării sistematice a fișierelor de sunet și a datelor audio. Deoarece există numeroase formate de fișier de sunet (recunoscute, de obicei, după extensiile lor, cum ar fi: `.wav`, `.aiff`, `.au`), veți avea de construit și de întreținut o colecție crescândă de module care să se ocupe cu conversia între diversele formate de fișier. De asemeni, există felurite operații pe care veți dori să le aplicați unor date audio (precum mixaje, adăugarea de ecouri, aplicarea unor funcții de egalizare, crearea unor efecte stereo artificiale), astfel că, pe lângă cele de dinainte, veți scrie în permanență noi module pentru aceste operații. Iată o structură posibilă a pachetului dumneavoastră (exprimată în stilul unui sistem ierarhic de fișiere – în englezește, ca jargon, filesystem):

    sound/                          Top-level package
          __init__.py               Initialize the sound package
          formats/                  Subpackage for file format conversions
                  __init__.py
                  wavread.py
                  wavwrite.py
                  aiffread.py
                  aiffwrite.py
                  auread.py
                  auwrite.py
                  ...
          effects/                  Subpackage for sound effects
                  __init__.py
                  echo.py
                  surround.py
                  reverse.py
                  ...
          filters/                  Subpackage for filters
                  __init__.py
                  equalizer.py
                  vocoder.py
                  karaoke.py
                  ...

Atunci când importăm un pachet, Python-ul va căuta subdirectorul pachetului în lista de directoare din `sys.path`.

Prezența unui fișier `__init__.py` într-un director obligă Python-ul să trateze respectivul director drept pachet (un astfel de fișier lipsește dacă folosim directorul pe post de pachet spațiu de nume, adică o caracteristică oarecum avansată a Python-ului despre care nu discutăm chiar acum). Acest procedeu face ca directoare cu nume banale, cum ar fi `string`, să nu poată conține, din pură întâmplare, module de interes ce ar trebui să fie găsite abia la locații ulterioare din calea de căutare a modulelor. În cel mai simplu caz, `__init__.py` este doar un fișier gol, însă el poate include, în general, cod de inițializare a pachetului ori o setare a variabilei `__all__`, la care ne vom referi mai târziu.

Utilizatorii unui pachet pot importa module individuale din acesta, ca de exemplu:

    import sound.effects.echo

Această instrucțiune încarcă submodulul `sunet.efecte.ecou`. Ne vom referi la el numai folosindu-i numele complet.

    sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)

Alt fel de a importa submodulul anterior este dat de:

    from sound.effects import echo

Și această instrucțiune încarcă submodulul `ecou`, pe care îl face accesibil fără prefixul cu nume de pachete, deci ne permite să-l întrebuințăm după cum urmează:

    echo.echofilter(input, output, delay=0.7, atten=4)

Încă o variație a modului de a importa este să importăm direct fie funcția fie variabila dorită:

    from sound.effects.echo import echofilter

Ca și până acum, instrucțiunea va încărca submodulul `ecou` însă ne va permite să folosim funcția `filtru_de_ecou()` din acesta numai cu numele ei:

    echofilter(input, output, delay=0.7, atten=4)

Să remarcăm că, atunci când executăm instrucțiunea `from pachet import element`, elementul poate fi sau un submodul (ori un subpachet) al pachetului sau orice alt nume definit în pachet, adică o funcție, o clasă ori o variabilă. Instrucțiunea `import` testează mai întâi dacă elementul este definit în pachet; dacă nu, atunci va presupune că elementul este numele unui modul și va încerca să-l încarce. În cazul în care presupusul modul nu va fi găsit, va fi ridicată o excepție `ImportError`.

În schimb, atunci când facem uz de o sintaxă de felul `import element.sub_element.sub_sub_element`, fiecare (sub)element, cu excepția ultimului, trebuie să fie nume de pachet; ultimul element poate fi sau nume de modul sau nume de pachet însă nu și numele vreunei clase, funcții ori variabile definite în elementul precedent.

### 6.4.1. Importând * dintr-un pachet

Ce se întâmplă însă atunci când utilizatorul folosește instrucțiunea `from sunet.efecte import *`? În mod ideal, putem spera că interpretorul se duce la sistemul de fișiere, găsește toate (sub)modulele prezente în pachet și le importă. O atare activitate este de așteptat să dureze mult iar importul de sub-module poate avea și efecte secundare nedorite pe care nu le-am produce dacă importul unui sub-modul oarecare ar fi realizat în mod explicit.

Singurul mod în care putem evita situațiile neplăcute este ca autorul pachetului să ofere un index explicit al acestuia. Instrucțiunea `import` folosește următoarea convenție: atunci când codul-sursă al fișierului `__init__.py` dintr-un pachet definește o variabilă de tip listă numită `__all__`, valoarea acestei variabile va fi folosită drept lista numelor de module ce vor trebui importate atunci când interpretorul va avea de executat instrucțiunea `from pachet import *`. Actualizarea listei de nume, cu ocazia lansării unei noi versiuni a pachetului, rămâne numai la latitudinea autorului acestuia. Autorii de pachete pot decide chiar și să nu întrebuințeze această facilitate atunci când nu consideră că ar fi de vreun folos să se importe * din pachetele lor. Ca exemplu, să presupunem că fișierul `sunet/efecte/__init__.py` ar conține următoarea linie de cod:

    __all__ = ["echo", "surround", "reverse"]

Aceasta ar însemna că, la execuția lui `from sunet.efecte import *`, vor fi importate cele trei submodule mai sus numite ale pachetului `sunet.efecte`.

Băgați de seamă că numele de (sub)module pot fi acoperite (de la englezescul shadowed; adică, au devenit invizibile pentru instrucțiunea curentă) de nume definite local. De exemplu, dacă ați adăugat definiția unei funcții `inversare` la codul-sursă al fișierului `sunet/efecte/__init__.py`, atunci execuția lui `from sunet.efecte import *` va produce importul celor două submodule `ecou` și `înconjurător` însă nu și importul submodulului `inversare` deoarece numele acestuia este acoperit de cel al funcției `inversare` definită local:

    __all__ = [
        "echo",      # refers to the 'echo.py' file
        "surround",  # refers to the 'surround.py' file
        "reverse",   # !!! refers to the 'reverse' function now !!!
    ]

    def reverse(msg: str):  # <-- this name shadows the 'reverse.py' submodule
        return msg[::-1]    #     in the case of a 'from sound.effects import *'

Atunci când `__all__` nu este definită, execuția instrucțiunii `from sunet.efecte import *` nu va produce importul tuturor submodulelor din pachetul `sunet.efecte` în spațiul de nume curent; tot ceea ce va face este să se asigure mai întâi că pachetul `sunet.efecte` a fost importat (ceea ce poate însemna inclusiv execuția codului de inițializare găsit în `__init__.py`), după care va importa toate numele definite în pachet. Aceasta va include numele (precum și submodulele încărcate explicit) din `__init__.py`. Va include, desigur, și toate submodulele pachetului care au fost deja încărcate explicit prin execuția precedentelor instrucțiuni `import`. Să luăm în considerare următoarele linii de cod:

    import sound.effects.echo
    import sound.effects.surround
    from sound.effects import *

În exemplul de față, modulele `ecou` și `înconjurător` sunt importate în spațiul de nume curent deoarece ele sunt definite în pachetul `sunet.efecte` la momentul execuției instrucțiunii `from...import`. (Ceea ce rămâne valabil și în cazul când `__all__` este definită.)

Cu toate că anumite module au fost proiectate să nu exporte decât acele nume care respectă șabloane precise atunci când dumneavoastră veți folosi instrucțiunea `import *` în raport de ele, întrebuințarea acestei instrucțiuni în codul destinat producției se socotește a fi o practică greșită.

Țineți minte, nu este nimic în neregulă dacă utilizați instrucțiunea `from pachet import submodulul_cutare`! De fapt, aceasta constituie chiar formularea recomandată a oricărei instrucțiuni de import, cu excepția situației în care modulul importator are de folosit submodule omonime din pachete diferite.

### 6.4.2. Referințe intra-pachet

Atunci când pachetele sunt organizate în subpachete (cum este cazul pachetului `sunet` din exemplul de mai sus), puteți folosi importurile absolute pentru a vă referi la submodule din (sub)pachete înrudite. Astfel, dacă presupunem că modulul `sunet.filtre.codare_vo` trebuie să utilizeze modulul `ecou` din pachetul `sunet.efecte`, atunci putem întrebuința instrucțiunea `from sunet.efecte import ecou`.

Puteți construi și instrucțiuni de import relativ, scrise sub forma `from modul import nume`. Aceste instrucțiuni de import vor folosi puncte de sine stătătoare pentru a indica fie pachetul curent fie pachetul-părinte al pachetului curent la care se referă importul relativ în cauză. Dacă scrieți cod situat, de exemplu, în modulul `înconjurător`, atunci ați putea utiliza formulele:

    from . import echo
    from .. import formats
    from ..filters import equalizer

Note that relative imports are based on the name of the current module. Since the name of the main module is always `"__main__"`, modules intended for use as the main module of a Python application must always use absolute imports.

### 6.4.3. Pachete situate în mai multe directoare

Packages support one more special attribute, `__path__`. This is initialized to be a list containing the name of the directory holding the package’s `__init__.py` before the code in that file is executed. This variable can be modified; doing so affects future searches for modules and subpackages contained in the package.

Deși este o caracteristică de care avem nevoie rar, o putem folosi cu succes la lărgirea setului de module conținute într-un pachet.

Note de subsol

[1]

De fapt, și definițiile de funcții sunt «instrucțiuni» care se «execută»; execuția unei definiții de funcție de la nivel de modul va adăuga numele acestei funcții la spațiul de nume global al modulului respectiv.