Oggetti tarFile¶
L’oggetto TarFile
fornisce un’interfaccia per un archivio tar. Un archivio tar è una sequenza di blocchi. Un membro dell’archivio (un file memorizzato) è composto da un blocco d’intestazione seguito da blocchi di dati. È possibile memorizzare un file in un archivio tar più volte. Ogni membro dell’archivio è rappresentato da un TarInfo
oggetto, vedi Oggetti TarInfo per i dettagli.
Un oggetto TarFile
può essere usato come gestore del contesto in un with
stato. Sarà automaticamente chiuso quando il blocco è completato. Si prega di notare che in caso di eccezione un archivio aperto per la scrittura non sarà finalizzato; solo l’oggetto file usato internamente sarà chiuso. Vedere la sezioneEsempi per un caso d’uso.
Nuovo nella versione 3.2: Aggiunto il supporto per il protocollo di gestione del contesto.
classtarfile.
TarFile
(name=None, mode=’r’, fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors=’surrogateescape’, pax_headers=None, debug=0, errorlevel=0)¶
Tutti i seguenti argomenti sono opzionali e possono essere accessibili anche come attributi di istanza.
name è il percorso dell’archivio. name può essere un oggetto simile a un percorso e può essere omesso se viene dato fileobj; in questo caso, l’attributo name
dell’oggetto file viene usato se esiste.
mode è 'r'
per leggere da un archivio esistente, 'a'
per aggiungere dati a un file esistente, 'w'
per creare un nuovo file sovrascrivendo uno esistente, o 'x'
per creare un nuovo file solo se non esiste già.
Se viene dato fileobj, viene usato per leggere o scrivere dati. Se può essere bedeterminato, il modo è sovrascritto dal modo di fileobj. fileobj sarà usato dalla posizione 0.
Nota
fileobj non è chiuso, quando TarFile
è chiuso.
format controlla il formato di archivio per la scrittura. Deve essere una delle costantiUSTAR_FORMAT
GNU_FORMAT
o PAX_FORMAT
che sono definite a livello di modulo. Durante la lettura, il formato sarà rilevato automaticamente, anche se sono presenti diversi formati in un singolo archivio.
L’argomento tarinfo può essere usato per sostituire la classe predefinita TarInfo
con una diversa.
Se il dereference è False
, aggiunge collegamenti simbolici e hard all’archivio. Se è True
, aggiungi il contenuto dei file di destinazione all’archivio. Questo non ha effetto sui sistemi che non supportano i collegamenti simbolici.
Se ignore_zeros è False
, tratta un blocco vuoto come la fine dell’archivio.Se è True
, salta i blocchi vuoti (e non validi) e cerca di ottenere più membri possibili. Questo è utile solo per leggere archivi concatenati o danneggiati.
debug può essere impostato da 0
(nessun messaggio di debug) fino a 3
(tutti i messaggi di debug). I messaggi sono scritti in sys.stderr
.
Se errorlevel è 0
, tutti gli errori sono ignorati quando si usa TarFile.extract()
. Se 1
, tutti gli errori fatali sono sollevati come OSError
eccezioni. Se 2
, anche tutti gli errori non fatali vengono sollevati come TarError
eccezioni.
Gli argomenti codifica ed errori definiscono la codifica dei caratteri da utilizzare per leggere o scrivere l’archivio e come verranno gestiti gli errori di conversione. Le impostazioni predefinite funzioneranno per la maggior parte degli utenti. Vedere la sezione Problemi Unicode per informazioni più approfondite.
L’argomento pax_headers è un dizionario opzionale di stringhe che saranno aggiunte come intestazione globale pax se il formato è PAX_FORMAT
.
Cambiato nella versione 3.2: Usa 'surrogateescape'
come predefinito per l’argomento errors.
Cambiato nella versione 3.5: È stato aggiunto il modo 'x'
(creazione esclusiva).
Cambiato nella versione 3.6: Il parametro name accetta un oggetto di tipo path.
classmethodTarFile.
open
(…)¶
Costruttore alternativo. La funzione tarfile.open()
è in realtà una scorciatoia per questo classmethod.
TarFile.
getmember
(name)¶
Ritorna un oggetto TarInfo
per il membro name. Se il nome non può essere trovato nell’archivio, viene sollevato KeyError
.
Nota
Se un membro compare più di una volta nell’archivio, la sua ultima occorrenza è assunta come la versione più aggiornata.
TarFile.
getmembers
()¶
Ritorna i membri dell’archivio come una lista di oggetti TarInfo
. La lista ha lo stesso ordine dei membri dell’archivio.
TarFile.
getnames
()¶
Ritorna i membri come una lista dei loro nomi. Ha lo stesso ordine della lista restituita da getmembers()
.
TarFile.
list
(verbose=True, *, members=None)¶
Stampa un indice a sys.stdout
. Se verbose è False
, vengono stampati solo i nomi dei membri. Se è True
, vengono prodotti output simili a quelli di ls -l. Se viene dato membri opzionale, deve essere un sottoinsieme della lista restituita da getmembers()
.
Cambiato nella versione 3.5: Aggiunto il parametro members.
Ritorna il prossimo membro dell’archivio come oggetto TarInfo
, quandoTarFile
viene aperto in lettura. Restituisce None
se non c’è altro disponibile.
TarFile.
extractall
(path=”.”, members=None, *, numeric_owner=False)¶
Estrarre tutti i membri dall’archivio nell’attuale directory di lavoro o percorso della directory. Se i membri opzionali sono dati, devono essere un sottoinsieme della lista restituita da getmembers()
. Le informazioni sulla directory come il proprietario, il tempo di modifica e i permessi sono impostati dopo che tutti i membri sono stati estratti; questo viene fatto per aggirare due problemi: Il tempo di modifica di una directory viene reimpostato ogni volta che viene creato un file in essa. E, se i permessi di una directory non permettono la scrittura, l’estrazione dei file in essa fallirà.
Se numeric_owner è True
, i numeri uid e gid dal tarfile sono usati per impostare il proprietario/gruppo per i file estratti. Altrimenti, vengono usati i valori nominativi del tarfile.
Attenzione
Non estrarre mai archivi da fonti non attendibili senza un controllo preventivo; è possibile che i file vengano creati fuori dal percorso, ad esempio membri che hanno nomi di file assoluti che iniziano con "/"
o nomi di file con due punti ".."
.
Cambiato nella versione 3.5: Aggiunto il parametro numeric_owner.
Cambiato nella versione 3.6: Il parametro path accetta un oggetto simile a path.
TarFile.
extract
(member, path=””, set_attrs=True, *, numeric_owner=False)¶
Estrarre un membro dall’archivio nella directory di lavoro corrente, usando il suo nome completo. Le informazioni sul suo file sono estratte nel modo più accurato possibile. member può essere un nome di file o un oggetto TarInfo
. Gli attributi dei file (proprietario, mtime, mode) sono impostati a meno che set_attrs sia false.
Se numeric_owner è True
, i numeri uid e gid dal tarfile sono usati per impostare il proprietario/gruppo dei file estratti. Altrimenti, vengono usati i valori nominativi dal tarfile.
Nota
Il metodo extract()
non si prende cura di diversi problemi di estrazione.Nella maggior parte dei casi dovresti considerare l’uso del metodo extractall()
.
Avviso
Vedi l’avviso per extractall()
.
Cambiato nella versione 3.2: Aggiunto il parametro set_attrs.
Cambiato nella versione 3.5: Aggiunto il parametro numeric_owner.
Cambiato nella versione 3.6: Il parametro path accetta un oggetto simile a path.
TarFile.
extractfile
(member)¶
Estrarre un member dall’archivio come oggetto file. member può essere un nome di file o un oggetto TarInfo
. Se il membro è un normale file o un link, viene restituito un oggetto io.BufferedReader
. Per tutti gli altri membri esistenti, viene restituito None
. Se il membro non appare nell’archivio, viene sollevato KeyError
.
Cambiato nella versione 3.3: Restituisce un oggetto io.BufferedReader
.
TarFile.
add
(name, arcname=None, recursive=True, *, filter=None)¶
Aggiunge il nome del file all’archivio. name può essere qualsiasi tipo di file (directory, fifo, link simbolico, etc.). Se dato, arcname specifica un nome alternativo per il file nell’archivio. Le directory sono aggiunte in modo ricorsivo per impostazione predefinita. Questo può essere evitato impostando recursive aFalse
. La ricorsione aggiunge le voci in ordine ordinato.Se viene dato filtro, dovrebbe essere una funzione che prende un TarInfo
argomento oggetto e restituisce l’oggetto TarInfo
modificato. Se invece restituisceNone
l’oggetto TarInfo
sarà escluso dall’archivio. Vedere Esempi per un esempio.
Cambiato nella versione 3.2: Aggiunto il parametro filter.
Cambiato nella versione 3.7: La ricorsione aggiunge voci in ordine ordinato.
TarFile.
addfile
(tarinfo, fileobj=None)¶
Aggiunge il TarInfo
oggetto tarinfo all’archivio. Se viene dato fileobj, dovrebbe essere un file binario, etarinfo.size
i byte vengono letti da esso e aggiunti all’archivio. Si possono creare oggetti TarInfo
direttamente, o usando gettarinfo()
.
TarFile.
gettarinfo
(name=None, arcname=None, fileobj=None)¶
Crea un oggetto TarInfo
dal risultato di os.stat()
o equivalente su un file esistente. Il file è o nominato per nome, o specificato come un oggetto fileobj con un descrittore di file.name può essere un oggetto simile a un percorso. Se dato, arcname specifica un nome alternativo per il file nell’archivio, altrimenti, il nome è preso dall’attributoname
di fileobj, o dall’argomento name. Il nome dovrebbe essere una stringa di testo.
È possibile modificare alcuni degli attributi di TarInfo
prima di aggiungerlo usando addfile()
.Se l’oggetto file non è un oggetto file ordinario posizionato all’inizio del file, attributi come size
potrebbero dover essere modificati. Questo è il caso di oggetti come GzipFile
.Anche il name
può essere modificato, nel qual caso arcnam potrebbe essere una stringa fittizia.
Cambiato nella versione 3.6: Il parametro name accetta un oggetto simile a un percorso.
TarFile.
close