6.1.4 File e directory

access( path, mode)
Usate gli uid/gid reali del processo corrente per verificare i permessi di accesso a path. Notate che la maggior parte delle operazioni useranno gli uid/gid effettivi, per cui questa funzione può venire usata in un ambiente suid/sgid, per verificare se l'utente che chiama la funzione può accedere a path. mode dovrebbe essere F_OK per verificare l'esistenza di path, oppure può essere l'OR inclusivo di uno o più tra i seguenti: R_OK, W_OK e X_OK per la verifica dei permessi. La funzione restituisce True se l'accesso è permesso, False altrimenti. Vedete la pagina di manuale della funzione Unix access(2) per maggiori informazioni. Disponibilità: Unix, Windows.

F_OK
Valore da passare al parametro mode della funzione access(), per verificare l'esistenza di path.

R_OK
Valore da includere nel parametro mode della funzione access(), per verificare la leggibilità di path.

W_OK
Valore da includere nel parametro mode della funzione access(), per verificare la scrivibilità di path.

X_OK
Valore da includere nel parametro mode della funzione access(), per determinare l'eseguibilità di path.

chdir( path)
Cambia la directory di lavoro corrente nel valore path. Disponibilità: Macintosh, Unix, Windows.

fchdir( fd)
Cambia la directory di lavoro corrente ponendola uguale alla directory rappresentata dal descrittore di file fd. Il descrittore deve riferirsi ad una directory aperta, non ad un file. Disponibilità: Unix. Nuovo nella versione 2.3.

getcwd( )
Restituisce una stringa rappresentante la directory di lavoro corrente. Disponibilità: Macintosh, Unix, Windows.

getcwdu( )
Restituisce un oggetto Unicode rappresentante la directory di lavoro corrente. Disponibilità: Unix, Windows. Nuovo nella versione 2.3.

chroot( path)
Cambia la directory radice del processo corrente nel valore path. Disponibilità: Unix. Nuovo nella versione 2.2.

chmod( path, mode)
Cambia il modo di path nel valore numerico mode. mode può prendere uno dei valori seguenti (come definiti nel modulo stat): Disponibilità: Unix, Windows.

chown( path, uid, gid)
Cambia l'identificativo del proprietario e del gruppo di path, ponendoli uguali ai valori numerici uid e gid. Disponibilità: Unix.

lchown( path, uid, gid)
Cambia l'identificativo del proprietario e del gruppo di path, ponendoli uguali ai valori numerici uid e gid. Questa funzione non segue i link simbolici. Disponibilità: Unix. Nuovo nella versione 2.3.

link( src, dst)
Crea un link fisico che punta a 'src, nominandolo dst. Disponibilità: Unix.

listdir( path)
Restituisce una lista contenente i nomi degli elementi della directory. La lista è in ordine arbitrario. Non include gli elementi speciali '.' e '..' benchè presenti nella directory. Disponibilità: Macintosh, Unix, Windows.

Modificato nella versione 2.3: Su Windows NT/2k/XP ed in Unix, se path è un oggetto Unicode, anche il risultato sarà una lista di oggetti Unicode..

lstat( path)
Come la funzione stat(), ma non segue i link simbolici. Disponibilità: Unix.

mkfifo( path[, mode])
Crea una FIFO (una pipe con un nome) chiamata come il valore del parametro path e avente come modo il valore numerico del parametro mode. Il valore predefinito di mode è 0666 (ottale). Il valore corrente della umask viene prima applicato come maschera a mode. Disponibilità: Unix.

Le FIFO sono pipe a cui si può accedere come a dei file regolari. Le FIFO continuano ad esistere finché non vengono cancellate (ad esempio con os.unlink()). Generalmente le FIFO vengono usate come sincronizzazione tra processi ``client'' e processi ``server'': il server apre la FIFO in lettura ed il client la apre in scrittura. Notate che mkfifo() non apre la FIFO -- crea solamente il punto di sincronizzzione.

mknod( path[, mode=0600, device])
Crea un nodo di filesystem (file regolare, file di dispositivo speciale, o una pipe con nome) chiamato come il valore del parametro filename. Il parametro mode specifica sia i permessi da usare che il tipo di nodo da creare, essendo una combinazione (con OR bit per bit) delle opzioni di permesso con uno tra: S_IFREG, S_IFCHR, S_IFBLK e S_IFIFO (queste costanti vengono definite nel modulo stat). Per S_IFCHR e S_IFBLK, il parametro device definisce il dispositivo speciale appena creato (probabilmente con os.makedev()), altrimenti viene ignorato. Nuovo nella versione 2.3.

major( device)
Estrae il numero maggiore di dispositivo da un numero di dispositivo grezzo. Nuovo nella versione 2.3.

minor( device)
Estrae il numero minore di dispositivo da un numero di dispositivo grezzo. Nuovo nella versione 2.3.

makedev( major, minor)
Compone un numero di dispositivo grezzo dai numeri maggiore e minore di dispositivo. Nuovo nella versione 2.3.

mkdir( path[, mode])
Crea una directory chiamata come il valore del parametro path con il modo numerico specificato dal parametro mode. Il modo predefinito è 0777 (ottale). In alcuni sistemi, mode viene ignorato. Dove usato, il valore corrente di umask viene prima applicato come maschera. Disponibilità: Macintosh, Unix, Windows.

makedirs( path[, mode])
Funzione di creazione di directory ricorsiva. Come mkdir(), ma tutte le directory intermedie conterranno quella finale. Solleva un'eccezione error se la directory finale esiste già o non può essere creata. Il modo predefinito è 0777 (ottale). Questa funzione non gestisce in modo corretto i percorsi UNC (di rilievo solo per sistemi Windows; i percorsi Universal Naming Convention) sono quelli che usano la sintassi `\\host\path'. Nuovo nella versione 1.5.2.

pathconf( path, name)
Restituisce i dati di configurazione del sistema relativi al file nominato. Il parametro name specifica il valore di configurazione da ottenere; può essere una stringa corrispondente al nome di un definito parametro di sistema; questi parametri vengono specificati in un certo numero di standard (POSIX.1, Unix 95, Unix 98 e altri). Alcune piattaforme definiscono nomi aggiuntivi. I nomi noti al sistema operativo ospite sono disponibili nel dizionario pathconf_names. Per le variabili di configurazione non incluse in questo dizionario, è accettabile passare un numero intero come valore di name. Disponibilità: Unix.

Se il parametro name è una stringa e non è nota, viene sollevata un'eccezione ValueError. Se un valore specifico per name non viene supportato dal sistema ospite anche se presente in pathconf_names, viene sollevata un'eccezione OSError con un valore pari a errno.EINVAL come codice di errore.

pathconf_names
Dizionario che mappa i nomi accettati da pathconf() e fpathconf() nei corrispondenti valori interi definiti dal sistema operativo ospite. Può venire usato per determinare l'insieme dei nomi conosciuti dal sistema. Disponibilità: Unix.

readlink( path)
Restituisce una stringa rappresentante il percorso a cui punta il link simbolico. Il risultato può essere un percorso relativo o assoluto; se è relativo, lo si può convertire in assoluto usando os.path.join(os.path.dirname(path), result). Disponibilità: Unix.

remove( path)
Rimuove il file indicato dal parametro path. Se path è una directory, viene sollevata un'eccezione OSError; vedete la funzione rmdir(), più avanti, per rimuovere una directory. Questa funzione è identica a functionunlink(), documentata più avanti. In Windows, cercare di rimuovere un file in uso causa il sollevamento di un'eccezione; in Unix, viene rimosso il riferimento al file nella directory, ma lo spazio allocato al file non viene reso disponibile fino al momento in cui il file non sia più in uso. Disponibilità: Macintosh, Unix, Windows.

removedirs( path)
Rimuove ricorsivamente le directory. Funziona come rmdir(), tranne per il fatto che, se la directory finale viene rimossa con successo, le directory via via corrispondenti al segmento più a destra del percorso specificato verrano ``potate'', fino a che l'intero percorso non sia stato cancellato, oppure non venga generato un errore (che viene ignorato, in quanto di solito questo significa che una directory genitrice non è vuota). Genera un'eccezione error se non è possibile rimuovere la directory finale. Nuovo nella versione 1.5.2.

rename( src, dst)
Rinomina il file o la directory src in dst. Se dst è una directory, viene sollevata un'eccezione OSError. Su Unix, se dst esiste ed è un file, viene rimosso senza avviso se l'utente ne ha il permesso. L'operazione può fallire su alcuni tipi di Unix se src e dst sono su filesystem diversi. In caso di successo, il cambio di nome sarà un'operazione atomica (questo è un requisito POSIX). In Windows, se dst esiste già, viene sollevata un'eccezione OSError anche se si tratta di un file; potrebbe non esistere modo di implementare una rinominazione atomica quando dst fa riferimento ad un file esistente. Disponibilità: Macintosh, Unix, Windows.

renames( old, new)
Funzione ricorsiva per il cambio di nome a directory e file. Funziona come rename(), eccetto che prima cerca di creare tutte le directory intermedie necessarie perché new sia un percorso valido. Dopo il cambio di nome, le directory via via corrispondenti alla parte più a destra del percorso old verranno rimosse utilizzando removedirs(). Nuovo nella versione 1.5.2.

Note: Questa funzione può fallire dopo aver creato la nuova struttura di directory, se l'utente non ha i permessi necessari per rimuovere la directory finale del percorso o il file. Nuovo nella versione 1.5.2.

rmdir( path)
Rimuove la directory indicata da path. Disponibilità: Macintosh, Unix, Windows.

stat( path)
Esegue una chiamata alla funzione di sistema stat() usando come argomento path. Il valore restituito è un oggetto i cui attributi corrispondono ai membri della struttura stat, e cioè: st_mode (bit di protezione), st_ino ( numero di inode), st_dev (dispositivo), st_nlink (numero di link fisici), st_uid (identificativo utente del proprietario), st_gid (identificativo di gruppo del proprietario), st_size (dimensione del file in byte), st_atime (tempo dell'accesso più recente), st_mtime (tempo della modifica dei contenuti più recente), st_ctime (dipende dalla piattaforma; tempo indicante il più recente cambiamento dei metadata su Unix, tempo di creazione su Windows).

Modificato nella versione 2.3: Se stat_float_times restituisce vero, i tempi sono dei numeri in virgola mobile che indicano secondi. Le frazioni di secondo possono venire indicate se il sistema lo supporta. Su Mac OS, i tempi sono sempre numeri in virgola mobile. Vedete stat_float_times per ulteriori dettagli. .

Su qualche tipo di Unix (ad esempio Linux), possono anche essere disponibili i seguenti attributi: st_blocks (numero di blocchi allocati per file), st_blksize (dimensione di un blocco usata dal filesystem), st_rdev (tipo di dispositivo, se si tratta di un inode che rappresenta un dispositivo).

Su sistemi Mac OS, possono anche essere disponibili i seguenti attributi: st_rsize, st_creator, st_type.

Su sistemi RISCOS, sono anche disponibili i seguenti attributi: st_ftype (tipo di file), st_attrs (attributi), st_obtype (tipo di oggetto).

Per compatibilità con le versioni precedenti, il valore restituito da stat() è anche accessibile come una tupla di almeno 10 numeri interi, che raccoglie i più importanti (e portabili) elementi della struttura stat, nell'ordine: st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid, st_size, st_atime, st_mtime, st_ctime. Altri elementi possono venire aggiunti tramite alcune implementazioni. Il modulo standard stat definisce le funzioni e le costanti utili per estrarre informazioni da una struttura stat. (Su Windows, ad alcuni elementi vengono assegnati valori fittizi). Disponibilità: Macintosh, Unix, Windows.

Modificato nella versione 2.2: Aggiunta la possibilità di accedere ai valori mediante gli attributi dell'oggetto restituito.

stat_float_times( [newvalue])
Determina se stat_result deve rappresentare i tempi come numeri in virgola mobile. Se newvalue vale True, chiamate successive a stat() restituiranno i valori in virgola mobile; se vale False, successive chiamate a stat() restituiranno i valori come interi. Se newvalue viene omesso, la funzione restituisce l'impostazione corrente.

Per compatibilità con precedenti versioni di Python, utilizzando stat_result come tupla si ottengono sempre interi. Per compatibilità con Python 2.2, anche accedendo ai valori dei tempi attraverso i nomi dei campi, si ottengono interi. Le applicazioni che vogliano ottenere le frazioni di secondo dei tempi possono usare questa funzione per ottenere i tempi espressi in numeri in virgola mobile. Se riusciranno o meno ad ottenere effettivamente frazioni diverse da zero dipenderà dal sistema sottostante.

Future versioni di Python cambieranno il valore predefinito di questa impostazione; applicazioni che non possono gestire i tempi espressi come numeri in virgola mobile potranno usare questa funzione per disattivare la caratteristica.

Si raccomanda di cambiare questa impostazione solo alla partenza del programma nel modulo __main__; le librerie non dovrebbero mai cambiare questa impostazione. Se un'applicazione usa una libreria che non funziona correttamente nell'elaborare i tempi dei file in forma di numeri in virgola mobile, questa applicazione dovrebbe disattivare la caratteristica fino a che la libreria non sia stata corretta.

statvfs( path)
Esegue una chiamata di sistema statvfs() sul percorso indicato. Il valore restituito è un oggetto i cui attributi descrivono il file system del percorso indicato, e corrispondono ai componenti della struttura statvfs e cioè: f_frsize, f_blocks, f_bfree, f_bavail, f_files, f_ffree, f_favail, f_flag, f_namemax. Disponibilità: Unix.

Per compatibilità con le versioni precedenti, il valore restituito è anche accessibile come tupla i cui elementi corispondono agli attributi dell'oggetto, nell'ordine descritto precedentemente. Il modulo standard statvfs definisce costanti che sono utili per estrarre informazioni da una struttura statvfs quando vi si accede come ad una sequenza; ciò è ancora utile qualora si scriva codice che deve funzionare con versioni di Python che non supportano l'accesso ai campi di statvfs in termini di attributi.

Modificato nella versione 2.2: Aggiunta la possibilità di accedere agli elementi di statvfs come attributi dell'oggetto restituito.

symlink( src, dst)
Crea un link simbolico che punta a src, chiamandolo dst. Disponibilità: Unix.

tempnam( [dir[, prefix]])
Restituisce un percorso unico che sia usabile per la creazione di un file temporaneo. Il valore restituito sarà un percorso assoluto che indica un potenziale file nella directory 'dir o in una directory comunemente usata per i file temporanei se dir non viene specificata o vale None. Se dir viene specificata e non è None, allora prefix viene usato per fornire un prefisso breve al nome del file. Le applicazioni hanno la responsabilità di creare e gestire correttamente i file creati usando i percorsi restituiti da tempnam(); non viene effettuata nessuna pulizia automatica dei file temporanei. In Unix, la variabile ambientale TMPDIR ha precedenza sul parametro dir, mentre in Windows viene usata la variabile TMP. Il comportamento specifico di questa funzione dipende dall'implementazione della sottostante libreria C; alcuni aspetti sono specificati in modo insufficiente nella documentazione di sistema. L'uso di tempnam() rende il programma vulnerabile ad attacchi di tipo symlink; considerate come alternativa l'uso di tmpfile(). Disponibilità: Unix, Windows.

tmpnam( )
Restituisce un percorso unico utilizzabile per creare un file temporaneo. Si tratterà di un percorso assoluto che corrisponde ad un potenziale file all'interno di una directory comunemente utilizzata per file temporanei. Le applicazioni sono responsabili di creare e gestire in modo appropriato i file creati utilizzando percorsi restituiti da tmpnam(); non viene fatta alcuna pulizia automatica. L'uso di tmpnam() rende il programma vulnerabile ad attacchi di tipo symlink; considerate come alternativa l'uso di tmpfile(). Disponibilità: Unix, Windows. Tuttavia questa funzione non dovrebbe essere usata in Windows, probabilmente: l'implementazione Microsoft di tmpnam() crea sempre un nome di file localizzato nella directory radice dell'unità corrente, e questa è generalmente una scelta infelice per un file temporaneo (a seconda dei privilegi, potreste non essere neanche in grado di aprire un file usando questo nome).

TMP_MAX
Il massimo numero di nomi unici che tmpnam() può generare prima di riusare nomi già generati.

unlink( path)
Rimuove il file indicato da path. Questa è la stessa funzione remove() con un altro nome; il nome unlink() è nella tradizione Unix. Disponibilità: Macintosh, Unix, Windows.

utime( path, times)
Imposta il tempo d'accesso e di modifica del file specificato da path. Se times vale None, allora i tempi di accesso e di modifica vengono impostati sul tempo corrente. Altrimenti times deve essere una coppia di numeri, della forma (atime, mtime), usati rispettivamente come tempo di accesso e di modifica. Modificato nella versione 2.0: Aggiunto il supporto per times uguale a None. Disponibilità: Macintosh, Unix, Windows.

walk( top[, topdown=True [, onerror=None]])
walk() genera i nomi dei file in un albero di directory, percorrendo l'albero dall'alto in basso o viceversa. Per ogni directory dell'albero con la radice in top (incluso lo stesso top), produce la tupla di 3 elementi (dirpath, dirnames, filenames).

dirpath è una stringa, corrispondente al percorso della directory. dirnames è una lista dei nomi delle sotto directory di dirpath (escluse '.' e '..'). filenames è una lista dei nomi dei file di tipo non directory contenuti in dirpath. Notate che i nomi in queste liste non contengono i percorsi. Per ottenere un percorso completo (relativo a top) per un file o una directory in dirpath, eseguite os.path.join(dirpath, name).

Se il parametro facoltativo topdown vale vero o non viene specificato, la tripla relativa ad una specifica directory viene sempre generata prima delle triple per ciascuna delle sue sotto directory. (le directory vengono generate dall'alto in basso). Se topdown vale falso, la tripla di una specifica directory viene generata dopo le triple di tutte le sue sotto directory (le directory vengono generate dal basso in alto).

Quando topdown vale vero, il chiamante può modificare la lista dirnames direttamente (ad esempio usando del o l'assegnamento di una fetta della lista), e walk() processerà solamente quelle directory i cui nomi sono ancora in dirnames; questo sistema può venire usato per limitare la ricerca, imporre un particolare ordine con cui le directory devono essere visitate o persino per comunicare a walk() i nomi di directory che create o rinominate dal chiamante prima che il controllo venga passato di nuovo a walk(). Modificare dirnames quando topdown vale falso non ha nessun effetto, perché procedendo dal basso verso l'alto, le directory in dirnames vengono analizzate prima di generare la stessa lista dirnames.

In modo predefinito, gli errori generati dalla chiamata a os.listdir() vengono ignorati. Se il parametro facoltativo onerror viene specificato, dovrebbe essere una funzione; tale funzione verrà chiamata con un argomento, che è un'istanza di os.error. La funzione può riportare l'errore e far procedere la scansione dell'albero, oppure può sollevare un'eccezione e far abortire la scansione. Notate che il nome del file relativo all'errore è disponibile come attributo filename dell'oggetto eccezione.

Note: Se passate alla funzione un percorso relativo, non cambiate la directory corrente di lavoro tra due continuazioni di walk(). walk() non cambia mai la directory corrente ed assume che il chiamante faccia lo stesso.

Note: Su sistemi che supportano i link simbolici, i link a sotto directory appaiono nelle liste dirnames, ma walk() non analizzerà queste directory (è difficile evitare dei loop infiniti quando si seguono link simbolici). Per analizare le directory indicate da link simbolici, potete identificarle usando os.path.islink(path) e quindi chiamare direttamente walk(path) su ciascuna di esse.

Questo esempio stampa il numero di byte usato da ciascun file, esclusi quelli di tipo directory, che si trovi in una sotto directory di quella di partenza, escluse le directory CVS e le loro sotto directory.

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/email'):
    print root, "usa",
    print sum([getsize(join(root, name)) for name in files]),
    print "byte in", len(files), "file di tipo non directory"
    if 'CVS' in dirs:
        dirs.remove('CVS')  # non visitare directory CVS

Nel prossimo esempio, il fatto di percorrere l'albero dal basso in alto è essenziale: rmdir() non permette di cancellare una directory se questa non è vuota.

import os
from os.path import join
# Cancella tutto ciò che è raqggiungibile dalla directory
# indicata in 'top'
# ATTENZIONE: è pericoloso! Per esempio se top == '/'
# potrebbe cancellare tutti i vostri file sul disco!!
for root, dirs, files in os.walk(top, topdown=False):
    for name in files:
        os.remove(join(root, name))
    for name in dirs:
        os.rmdir(join(root, name))

Nuovo nella versione 2.3.

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