3.21 `imp` -- Accesso alle caratteristiche interne dell'istruzione `import`

Questo modulo fornisce un'interfaccia ai meccanismi usati per implementare l'istruzione import. Definisce le seguenti costanti e funzioni:

get_magic( ): Restituisce il valore della magic string usata per riconoscere i file con codice bytecode (file (.pyc). (Questo valore può differire per ogni versione di Python.)

get_suffixes( ): Restituisce una lista di triple, ciascuna delle quali descrive un particolare tipo di modulo. Ogni tripla ha la struttura (suffix, mode, type), dove suffix è una stringa da aggiungere al nome del modulo per creare il nome del file da cercare, mode è la stringa della modalità da passare alla funzione built-in open() per aprire file (questa può essere 'r' per file di testo o 'rb' per file binari), e type è il tipo di file, che può assumere uno dei valori PY_SOURCE, PY_COMPILED, o C_EXTENSION, descritti più avanti.

find_module( name[, path])

Cerca di trovare il modulo name nel percorso di ricerca path. Se path è una lista di nomi di directory, all'interno di ognuna di esse viene eseguita la ricerca in base alle estensioni restituite dalla funzione get_suffixes(). Nomi non validi vengono tacitamente ignorati (ma tutti gli elementi della lista devono essere stringhe). Se path viene omesso o è uguale a None, la ricerca avviene nei percorsi contenuti in sys.path, ma dopo aver cercato in alcuni luoghi speciali: innanzitutto prova a cercare un modulo built-in con il nome dato (C_BUILTIN), poi tra i moduli frozen (PY_FROZEN), e così via in altri luoghi dipendenti dal sistema (su Mac, si cerca tra le risorse (PY_RESOURCE); su Windows, nel registro di configurazione, che potrebbe puntare ad uno specifico file).

Se la ricerca ha successo, il valore restituito è una tripla (file, pathname, description) dove file è un oggetto file aperto posto all'inizio della tripla, pathname è il percorso del file trovato e description è una tripla identica a quella restituita dalla funzione get_suffixes(), che descrive il tipo di modulo trovato. Se il modulo non è in un file, il file restituito è None, filename è una stringa vuota, e description contiene stringhe vuote per i suffissi e modi del modulo; il tipo di modulo viene indicato tra parentesi, come sopra. Se la ricerca non ha successo, viene sollevata l'eccezione ImportError. ALtre eccezioni indicano problemi relativi agli argomenti o all'ambiente.

Questa funzione non gestisce i nomi di modulo gerarchici (nomi contenenti punti). Per poter trovare P.M, cioè il modulo derivato M del package P, usate find_module() e load_module() per trovare e caricare P, e quindi find_module() con l'argomento path impostato a P.__path__. Nel caso in cui P stesso abbia un nome con caratteri punto, applicate il procedimento ricorsivamente.

load_module( name, file, filename, description)

Carica un modulo precedentemente trovato da find_module() (o da qualsiasi altra ricerca che restituisca un risultato compatibile). Questa funzione fa più che importare il modulo: se il modulo era già stato importato, è equivalente ad un reload()! L'argomento name indica il nome completo del modulo (compreso il nome del package, se si tratta di un suo modulo derivato). L'argomento file è un file aperto e filename è il corrispondente nome del file; questi possono essere None e '', rispettivamente, quando il modulo non viene caricato da un file. L'argomento description è una tupla, identica a quella restituita da get_suffixes(), che descrive il tipo di modulo da caricare.

Se il caricamento avviene con successo, il valore restituito è l'oggetto modulo; altrimenti, viene sollevata un'eccezione (di solito ImportError).

Importante: il chiamante è anche responsabile di chiudere l'argomento file, se questo non era None, anche quando viene sollevata un'eccezione. Questo scopo viene raggiunto in modo ottimale usando l'istruzione try ... finally.

new_module( name): Restituisce un nuovo oggetto modulo vuoto chiamato name. Questo oggetto non viene inserito in sys.modules.

lock_held( ): Restituisce True se il lock al modulo viene correntemente mantenuto, altrimenti False. Su piattaforme che non supportano thread, restituisce sempre False.
Su piattaforme che supportano i thread, un thread che esegue un import mantiene un lock interno finchè l'import non viene completato. Questo lock blocca altri thread che pure tentino di eseguire un import fino a quando il primo import non è terminato, prevenendo così la possibilità che gli altri thread vedano oggetti modulo ancora incompleti prima che l'import sia stato completato (anche altri eventuali import presenti vengono bloccati).

acquire_lock( ): Acquisisce il lock dell'import dell'interprete nel thread corrente. Questo lock dovrebbe venire usato come estensioni al meccanismo di import per garantire che i thread vengano gestiti in maniera sicura quando si importano dei moduli. Su piattaforme che non supportano i thread, questa funzione non fa niente. Nuovo nella versione 2.3.

release_lock( ): Rilascia il lock dell'interprete per l'import. Su piattaforme che non supportano i thread questa funzione non fa niente. Nuovo nella versione 2.3.

Le seguenti costanti a valori interi, definite in questo modulo, vengono usate per indicare il risultato della ricerca di find_module().

PY_SOURCE: Il modulo trovato è un file sorgente.

PY_COMPILED: Il modulo trovato è un file compilato in codice oggetto.

C_EXTENSION: Il modulo trovato è una libreria condivisa caricabile dinamicamente.

PY_RESOURCE: Il modulo trovato è una risorsa Macintosh. Questo valore può essere restituito solo su un Macintosh.

PKG_DIRECTORY: Il modulo trovato è una directory package.

C_BUILTIN: Il modulo trovato è un modulo built-in.

PY_FROZEN: Il modulo trovato è un modulo frozen (vedete init_frozen()).

Le seguenti costanti e funzioni sono obsolete; le loro funzionalità vengono rese disponibili tramite find_module() o load_module(). Vengono mantenute per compatibilità all'indietro.

SEARCH_ERROR: Non usata.

init_builtin( name): Inizializza il modulo built-in chiamato name e restituisce il suo modulo oggetto. Se il modulo è già stato inizializzato, verrà inizializzato nuovamente. Alcuni moduli non possono venire inizializzati due volte -- tentando di inizializzarli nuovamente, solleveranno un'eccezione ImportError. Se non ci sono moduli built-in chiamati name, viene restituito None.

init_frozen( name): Inizializza il modulo frozen chiamato name e restituisce il suo modulo oggetto. Se il modulo è già stato inizializzato, verrà inizializzato nuovamente. Se non esistono moduli frozen chiamati name, viene restituito None. (I moduli frozen sono moduli scritti in Python il cui oggetto compilato in bytecode viene incorporato in un interprete Python personalizzato, attraverso l'utility Python freeze. Vedete, per adesso, Tools/freeze/.)

is_builtin( name): Restituisce 1 se esiste un modulo built-in chiamato name che può essere inizializzato nuovamente. Restituisce -1 se esiste un modulo built-in chiamato name che non può essere inizializzato nuovamente (vedete init_builtin()). Restituisce 0 se non esistono moduli built-in chiamati name.

is_frozen( name): Restituisce True se esiste un modulo frozen (vedete init_frozen()) chiamato name, o False se non esiste il modulo.

load_compiled( name, pathname, file): Carica ed inizializza un modulo implementato come codice compilato in bytecode e restituisce il suo modulo oggetto. Se il modulo è già stato inizializzato, verrà inizializzato nuovamente. L'argomento name viene usato per creare o accedere al modulo oggetto. L'argomento pathname punta al file del bytecode compilato. L'argomento file è il file del codice bytecode compilato, aperto in lettura in modo binario, all'inizio. Deve essere un file oggetto reale, non una classe definita dall'utente che emula un file.

load_dynamic( name, pathname[, file]): Carica e inizializza un modulo implementato come libreria condivisa dinamicamente caricabile e restituisce il suo modulo oggetto. Se il modulo è già inizializzato, verrà inizializzato nuovamente. Ad alcuni moduli non piace la reinizializzazione e potrebbero sollevare un'eccezione. L'argomento pathname deve puntare alla libreria condivisa. L'argomento name viene usato per costruire il nome della funzione di inizializzazione: viene chiamata una funzione C esterna chiamata "initname()" nella libreria condivisa. L'argomento facoltativo file viene ignorato. (Nota: l'uso delle librerie dinamiche è altamente legato al sistema in uso, e non tutti i sistemi lo supportano).

load_source( name, pathname, file): Carica e inizializza un modulo implementato come file di codice sorgente Python e restituisce il suo modulo oggetto. Se il modulo è già inizializzato, verrà inizializzato nuovamente. L'argomento name viene usato per creare un modulo oggetto, o accedervi. L'argomento pathname punta al file sorgente. L'argomento file è il file sorgente, aperto in lettura come testo, dall'inizio. Deve essere un file oggetto reale, non una classe definita dall'utente che emula un file. Notate che se un file compilato in bytecode risulta propriamente corrispondente (con il suffisso .pyc o .pyo) esiste, verrà usato questo piuttosto che far analizzare al parser il file sorgente indicato.

Vedete Circa questo documento... per informazioni su modifiche e suggerimenti.

3.21 imp -- Accesso alle caratteristiche interne dell'istruzione import

3.21 `imp` -- Accesso alle caratteristiche interne dell'istruzione `import`