DESCRIPTION.

Retourne le contenu d'un répertoire, d'un dossier.

SYNTAXE.

LST_Variable = os.scandir ( chemin )

LST_Variable = ⇨ variable qui recevra la valeur [ optionnel ]

os.scandir ( ) ⇨ appel de la méthode [ OBLIGATOIRE ]

chemin ⇨ emplacement [ OBLIGATOIRE ]

REMARQUES.

chemin doit être un str ( ), ou un bytes ( ), identifiant le chemin d'un répertoire valide. chemin peut être exprimé en : 

- chemin absolu, par exemple, sous Linux, "/home/origine/Documents" ;

- chemin relatif, par exemple, sous Linux, "./Programmes" pour le dossier Programmes dans le répertoire de travail actuel.

L'appel de la méthode os.scandir ( ) retourne un objet itérateur de type os.DirEntry ( ), dont les éléments sont : soit des noms fichiers ; soit des noms de sous-répertoires, dans un ordre indéterminé, en incluant d'éventuels éléments cachés. Si elles se trouvent dans chemin, les représentations spéciales "." et ".." ne seront inclus dans l'objet os.DirEntry retourné.

Si chemin est exprimé avec un objet de type bytes ( ), les éléments de chemin seront aussi du type bytes ( ), dans les autres cas, ils seront sous une forme str ( ).

Si la composition de chemin est modifiée, par exemple avec la création ou la suppression d'un élément, durant l'appel de la méthode os.scandir ( ), cette modification ne sera pas prise en compte dans l'objet os.DirEntry retourné.

Depuis Python 3.3, chemin peut faire référence à un descripteur de fichier, si ce descripteur est associé à un répertoire ouvert et non à un fichier ouvert.

Si chemin est omis, la méthode os.scandir ( ) retournera le contenu du répertoire de travail.

Si chemin n'existe pas, Python lèvera une exception.

L'utilisation de la méthode os.scandir ( ), à la place de la méthode os.listdir ( ), accroitra la pertinence d'un code, en fournissant le mode d'accès et les attributs des fichiers, puisque l'objet os.DirEntry ( ) permet de disposer ces données, si le système d'exploitation les fournit en scannant chemin. 

L'appel de la sous-méthode os.scandir.close ( ) videra et terminera l'itérateur obtenu par l'appel de os.scandir ( ) puis libérera les ressources qui lui étaient dévolues. 

Bien que la sous-méthode os.scandir.close ( ) soit invoquée automatiquement quand l'objet os.DirEntry est entièrement parcourru, il est fortement conseillé d'utiliser la méthode os.scandir ( ) protégé par encapsulage de l'instruction with.

Les objets itérables, de la classe os.DirEntry ( ) , retournés par la a méthode os.scandir ( ) disposent des attributs et méthodes suivantes.

os.DirEntry ( ).name

Cet attribut contient le nom de l'élément, relatif à l'argument chemin donné à l'appel de os.scandir ( ). Il est du type bytes ( ) si chemin est de type bytes ( ) sinon il sera du type str ( ). Voir la méthode os.fsdecode ( ) pour convertir des noms de fichiers de types bytes ( )  en str ( ).

os.DirEntry ( ).path

Cet attribut contient le nom complet de l'élément, c'est-à-dire le chemin absolu de l'élément, si l'argument chemin donné à l'appel de os.scandir ( ) était exprimé en chemin absolu. Si chemin est un descripteur de fichier,  os.DirEntry ( ).path aura la même valeur que os.DirEntry ( ).name. Il est du type bytes ( ) si chemin est de type bytes ( ) sinon il sera du type str ( ). Voir la méthode os.fsdecode ( ) pour convertir des noms de fichiers de types bytes ( )  en str ( ).

os.DirEntry ( ).inode ( )

Cette méthode retourne le numéro d'inode de l'élément. 

os.DirEntry ( ).is_dir ( )

Cette méthode retourne True si l'élément est un répertoire, ou un lien symbolique associé à un répertoire, sinon False.  os.DirEntry ( ).is_dir ( ) accepte un argument, optionnel, follow_symlinks = bool . Si bool vaut False, alors l'appel de la méthode os.DirEntry ( ).is_dir ( ) ne tiendra pas compte des liens symboliques et retournera True uniquement si l'élément est un répertoire.

os.DirEntry ( ).is_file ( )

Cette méthode retourne True si l'élément est un fichier, ou un lien symbolique associé à un fichier, sinon False.  os.DirEntry ( ).is_file ( ) accepte un argument, optionnel, follow_symlinks = bool . Si bool vaut False, alors l'appel de la méthode os.DirEntry ( ).is_file ( ) ne tiendra pas compte des liens symboliques et retournera True uniquement si l'élément est un fichier.

os.DirEntry ( ).is_symlink ( )

Cette méthode retourne True un lien symbolique associé à un fichier, même s'il n'est plus associé à un emplacement, sinon False.

os.DirEntry ( ).stat ( )

Cette méthode retourne un objet de type stat.result pour cette l'élément. L'appel standard de la méthode os.DirEntry ( ).stat ( ) suit les liens symboliques par défaut. Pour avoir les statistiques sur un lien symbolique, ajouter l'argument, optionnel, follow_symlinks = False. Voir la méthode os.stat ( ) pour les restrictions et  les détails des informations retournées par les objets de type stat.result.

A noter la grande similarité entre les classes os.DirEntry ( ) et pathlib.Path ( ).

EXEMPLE.

import os

LST_Caches = [ ]

LST_Fichiers = [ ]

LST_Repertoires = [ ]

kcourant = os.getcwd ( )

print ( "Votre répertoire de travail se nomme" , kcourant )

with os.scandir ( kcourant ) as kemplacements :

for kelement in kemplacements :

if kelement.name.startswith ( "." ) : LST_Caches.append ( kelement.name )

elif kelement.is_file ( ) : LST_Fichiers.append ( kelement.name )

else : LST_Repertoires.append ( kelement.name )

if len ( LST_Fichiers ) != 0 :

print ( "Il contient le(s) fichier(s) :" )

for kfichier in LST_Fichiers : print ( "-" , kfichier )

else :

print ( "Il ne contient aucun fichier." )

if len ( LST_Repertoires ) != 0 :

print ( "Il contient le(s) répertoire(s) :" )

for krepertoire in LST_Repertoires : print ( "-" , krepertoire )

else :

print ( "Il ne contient aucun répertoire." )

if len ( LST_Caches ) != 0 :

print ( "Il contient le(s) éléments(s) caché(s):" )

for kobjet in LST_Caches : print ( "-" , kobjet )

else :

print ( "Il ne contient aucun élément caché." )