11.1. `pathlib` — Chemins de système de fichiers orientés objet¶

Nouveau dans la version 3.4.

Ce module offre des classes représentant le système de fichiers avec la sémantique appropriée pour différents systèmes d’exploitation. Les classes de chemins sont divisées en chemins purs, qui fournissent purement du calcul sans entrées/sorties, et chemins concrets, qui héritent des chemins purs et fournissent également les opérations d’entrées/sorties.

Si vous n’avez jamais utilisé ce module précédemment, ou si vous n’êtes pas sûr de quelle classe est faite pour votre tâche, Path est très certainement ce dont vous avez besoin. Elle instancie un chemin concret pour la plateforme sur laquelle s’exécute le code.

Les chemins purs sont utiles dans certains cas particuliers ; par exemple :

Si vous voulez manipuler des chemins Windows sur une machine Unix (ou vice versa). Vous ne pouvez pas instancier un WindowsPath quand vous êtes sous Unix, mais vous pouvez instancier PureWindowsPath.
Vous voulez être sûr que votre code manipule des chemins sans réellement accéder au système d’exploitation. Dans ce cas, instancier une de ces classes pures peut être utile puisqu’elle ne possède tout simplement aucune opération permettant d’accéder au système d’exploitation.

Voir aussi

PEP 428 : Le module pathlib – chemins de système de fichiers orientés objet.

Voir aussi

Pour de la manipulation de chemins bas-niveau avec des chaînes de caractères, vous pouvez aussi utiliser le module os.path.

11.1.1. Utilisation basique¶

Importer la classe principale :

>>> from pathlib import Path

Lister les sous-dossiers :

>>> p = Path('.')
>>> [x for x in p.iterdir() if x.is_dir()]
[PosixPath('.hg'), PosixPath('docs'), PosixPath('dist'),
 PosixPath('__pycache__'), PosixPath('build')]

Lister les fichiers source Python dans cette arborescence de dossiers :

>>> list(p.glob('**/*.py'))
[PosixPath('test_pathlib.py'), PosixPath('setup.py'),
 PosixPath('pathlib.py'), PosixPath('docs/conf.py'),
 PosixPath('build/lib/pathlib.py')]

Naviguer à l’intérieur d’une arborescence de dossiers :

>>> p = Path('/etc')
>>> q = p / 'init.d' / 'reboot'
>>> q
PosixPath('/etc/init.d/reboot')
>>> q.resolve()
PosixPath('/etc/rc.d/init.d/halt')

Récupérer les propriétés de chemin :

>>> q.exists()
True
>>> q.is_dir()
False

Ouvrir un fichier :

>>> with q.open() as f: f.readline()
...
'#!/bin/bash\n'

11.1.2. Chemins purs¶

Les objets chemins purs fournissent les opérations de gestion de chemin qui n’accèdent pas réellement au système de fichiers. Il y a trois façons d’accéder à ces classes que nous appelons aussi familles :

class pathlib.PurePath(*pathsegments)¶

Une classe générique qui représente la famille de chemin du système (l’instancier crée soit un PurePosixPath soit un PureWindowsPath) :

>>> PurePath('setup.py')      # Running on a Unix machine
PurePosixPath('setup.py')

Chaque élément de pathsegments peut soit être une chaîne de caractères représentant un segment de chemin, un objet implémentant l’interface os.PathLike qui renvoie une chaîne de caractères, soit un autre objet chemin :

>>> PurePath('foo', 'some/path', 'bar')
PurePosixPath('foo/some/path/bar')
>>> PurePath(Path('foo'), Path('bar'))
PurePosixPath('foo/bar')

Quand pathsegments est vide, le dossier courant est utilisé :

>>> PurePath()
PurePosixPath('.')

Quand plusieurs chemins absolus sont fournis, le dernier est pris comme ancre (recopiant le comportement de os.path.join()) :

>>> PurePath('/etc', '/usr', 'lib64')
PurePosixPath('/usr/lib64')
>>> PureWindowsPath('c:/Windows', 'd:bar')
PureWindowsPath('d:bar')

Cependant, dans un chemin Windows, changer la racine locale ne supprime pas la précédente configuration de lecteur :

>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')

Les points et slashs malencontreux sont supprimés, mais les doubles points ('..') ne le sont pas, puisque cela changerait la signification du chemin dans le cas de liens symboliques :

>>> PurePath('foo//bar')
PurePosixPath('foo/bar')
>>> PurePath('foo/./bar')
PurePosixPath('foo/bar')
>>> PurePath('foo/../bar')
PurePosixPath('foo/../bar')

(une analyse naïve considérerait PurePosixPath('foo/../bar') équivalent à PurePosixPath('bar'), ce qui est faux si foo est un lien symbolique vers un autre dossier)

Les objets chemins purs implémentent l’interface os.PathLike, leur permettant d’être utilisés n’importe où l’interface est acceptée.

Modifié dans la version 3.6: Ajout de la gestion de l’interface os.PathLike.

class pathlib.PurePosixPath(*pathsegments)¶

Une sous-classe de PurePath, cette famille de chemin représente les chemins de systèmes de fichiers en dehors des chemins Windows :

>>> PurePosixPath('/etc')
PurePosixPath('/etc')

pathsegments est spécifié de manière similaire à PurePath.

class pathlib.PureWindowsPath(*pathsegments)¶

Une sous-classe de PurePath, cette famille de chemin représente les chemins de systèmes de fichiers Windows :

>>> PureWindowsPath('c:/Program Files/')
PureWindowsPath('c:/Program Files')

pathsegments est spécifié de manière similaire à PurePath.

Sans tenir compte du système sur lequel vous êtes, vous pouvez instancier toutes ces classes, puisqu’elles ne fournissent aucune opération qui appelle le système d’exploitation.

11.1.2.1. Propriétés générales¶

Les chemins sont immuables et hachables. Les chemins d’une même famille sont comparables et ordonnables. Ces propriétés respectent l’ordre lexicographique défini par la famille :

>>> PurePosixPath('foo') == PurePosixPath('FOO')
False
>>> PureWindowsPath('foo') == PureWindowsPath('FOO')
True
>>> PureWindowsPath('FOO') in { PureWindowsPath('foo') }
True
>>> PureWindowsPath('C:') < PureWindowsPath('d:')
True

Les chemins de différentes familles ne sont pas égaux et ne peuvent être ordonnés :

>>> PureWindowsPath('foo') == PurePosixPath('foo')
False
>>> PureWindowsPath('foo') < PurePosixPath('foo')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: '<' not supported between instances of 'PureWindowsPath' and 'PurePosixPath'

11.1.2.2. Opérateurs¶

L’opérateur slash aide à créer les chemins enfants, de manière similaire à os.path.join() :

>>> p = PurePath('/etc')
>>> p
PurePosixPath('/etc')
>>> p / 'init.d' / 'apache2'
PurePosixPath('/etc/init.d/apache2')
>>> q = PurePath('bin')
>>> '/usr' / q
PurePosixPath('/usr/bin')

Un objet chemin peut être utilisé n’importe où un objet implémentant os.PathLike est accepté :

>>> import os
>>> p = PurePath('/etc')
>>> os.fspath(p)
'/etc'

La représentation d’un chemin en chaîne de caractères est celle du chemin brut du système de fichiers lui-même (dans sa forme native, i.e. avec des antislashs sous Windows), et que vous pouvez passer à n’importe quelle fonction prenant un chemin en tant que chaîne de caractères :

>>> p = PurePath('/etc')
>>> str(p)
'/etc'
>>> p = PureWindowsPath('c:/Program Files')
>>> str(p)
'c:\\Program Files'

De manière similaire, appeler bytes sur un chemin donne le chemin brut du système de fichiers en tant que bytes, tel qu’encodé par os.fsencode() :

>>> bytes(p)
b'/etc'

Note

Appeler bytes est seulement recommandé sous Unix. Sous Windows, la forme Unicode est la représentation canonique des chemins du système de fichiers.

11.1.2.3. Accéder aux parties individuelles¶

Pour accéder aux parties individuelles (composantes) d’un chemin, utilisez les propriétés suivantes :

PurePath.parts¶

Un tuple donnant accès aux différentes composantes du chemin :

>>> p = PurePath('/usr/bin/python3')
>>> p.parts
('/', 'usr', 'bin', 'python3')

>>> p = PureWindowsPath('c:/Program Files/PSF')
>>> p.parts
('c:\\', 'Program Files', 'PSF')

(notez comme le lecteur et la racine locale sont regroupés en une seule partie)

11.1.2.4. Méthodes et propriétés¶

Les chemins purs fournissent les méthodes et propriétés suivantes :

PurePath.drive¶

Une chaîne représentant la lettre du lecteur ou le nom, s’il y en a un :

>>> PureWindowsPath('c:/Program Files/').drive
'c:'
>>> PureWindowsPath('/Program Files/').drive
''
>>> PurePosixPath('/etc').drive
''

Les partages UNC sont aussi considérés comme des lecteurs :

>>> PureWindowsPath('//host/share/foo.txt').drive
'\\\\host\\share'

PurePath.root¶

Une chaîne de caractères représentant la racine (locale ou globale), s’il y en a une :

>>> PureWindowsPath('c:/Program Files/').root
'\\'
>>> PureWindowsPath('c:Program Files/').root
''
>>> PurePosixPath('/etc').root
'/'

Les partages UNC ont toujours une racine :

>>> PureWindowsPath('//host/share').root
'\\'

PurePath.anchor¶

La concaténation du lecteur et de la racine :

>>> PureWindowsPath('c:/Program Files/').anchor
'c:\\'
>>> PureWindowsPath('c:Program Files/').anchor
'c:'
>>> PurePosixPath('/etc').anchor
'/'
>>> PureWindowsPath('//host/share').anchor
'\\\\host\\share\\'

PurePath.parents¶

Une séquence immuable fournissant accès aux ancêtres logiques du chemin :

>>> p = PureWindowsPath('c:/foo/bar/setup.py')
>>> p.parents[0]
PureWindowsPath('c:/foo/bar')
>>> p.parents[1]
PureWindowsPath('c:/foo')
>>> p.parents[2]
PureWindowsPath('c:/')

PurePath.parent¶

Le parent logique du chemin :

>>> p = PurePosixPath('/a/b/c/d')
>>> p.parent
PurePosixPath('/a/b/c')

Vous ne pouvez pas aller au-delà d’une ancre, ou d’un chemin vide :

>>> p = PurePosixPath('/')
>>> p.parent
PurePosixPath('/')
>>> p = PurePosixPath('.')
>>> p.parent
PurePosixPath('.')

Note

C’est une opération purement lexicale, d’où le comportement suivant :

>>> p = PurePosixPath('foo/..')
>>> p.parent
PurePosixPath('foo')

Si vous voulez parcourir un chemin arbitraire du système de fichiers, il est recommandé de d’abord appeler Path.resolve() de manière à résoudre les liens symboliques et éliminer les composantes « .. ».

PurePath.name¶

Une chaîne représentant la composante finale du chemin, en excluant le lecteur et la racine, si présent :

>>> PurePosixPath('my/library/setup.py').name
'setup.py'

Les noms de lecteur UNC ne sont pas pris en compte :

>>> PureWindowsPath('//some/share/setup.py').name
'setup.py'
>>> PureWindowsPath('//some/share').name
''

PurePath.suffix¶

L’extension du fichier de la composante finale, si présente :

>>> PurePosixPath('my/library/setup.py').suffix
'.py'
>>> PurePosixPath('my/library.tar.gz').suffix
'.gz'
>>> PurePosixPath('my/library').suffix
''

PurePath.suffixes¶

Une liste des extensions du chemin de fichier :

>>> PurePosixPath('my/library.tar.gar').suffixes
['.tar', '.gar']
>>> PurePosixPath('my/library.tar.gz').suffixes
['.tar', '.gz']
>>> PurePosixPath('my/library').suffixes
[]

PurePath.stem¶

La composante finale du chemin, sans son suffixe :

>>> PurePosixPath('my/library.tar.gz').stem
'library.tar'
>>> PurePosixPath('my/library.tar').stem
'library'
>>> PurePosixPath('my/library').stem
'library'

PurePath.as_posix()¶

Renvoie une représentation en chaîne de caractères du chemin avec des slashs (/) :

>>> p = PureWindowsPath('c:\\windows')
>>> str(p)
'c:\\windows'
>>> p.as_posix()
'c:/windows'

PurePath.as_uri()¶

Représente le chemin en tant qu’URI de fichier. ValueError est levée si le chemin n’est pas absolu.

>>> p = PurePosixPath('/etc/passwd')
>>> p.as_uri()
'file:///etc/passwd'
>>> p = PureWindowsPath('c:/Windows')
>>> p.as_uri()
'file:///c:/Windows'

PurePath.is_absolute()¶

Renvoie si le chemin est absolu ou non. Un chemin est considéré absolu s’il a une racine et un lecteur (si la famille le permet) :

>>> PurePosixPath('/a/b').is_absolute()
True
>>> PurePosixPath('a/b').is_absolute()
False

>>> PureWindowsPath('c:/a/b').is_absolute()
True
>>> PureWindowsPath('/a/b').is_absolute()
False
>>> PureWindowsPath('c:').is_absolute()
False
>>> PureWindowsPath('//some/share').is_absolute()
True

PurePath.is_reserved()¶

Avec PureWindowsPath, renvoie True si le chemin est considéré réservé sous Windows, False sinon. Avec PurePosixPath, False est systématiquement renvoyé.

>>> PureWindowsPath('nul').is_reserved()
True
>>> PurePosixPath('nul').is_reserved()
False

Les appels au système de fichier sur des chemins réservés peuvent échouer mystérieusement ou avoir des effets inattendus.

PurePath.joinpath(*other)¶

Appeler cette méthode équivaut à combiner le chemin avec chacun des arguments other :

>>> PurePosixPath('/etc').joinpath('passwd')
PurePosixPath('/etc/passwd')
>>> PurePosixPath('/etc').joinpath(PurePosixPath('passwd'))
PurePosixPath('/etc/passwd')
>>> PurePosixPath('/etc').joinpath('init.d', 'apache2')
PurePosixPath('/etc/init.d/apache2')
>>> PureWindowsPath('c:').joinpath('/Program Files')
PureWindowsPath('c:/Program Files')

PurePath.match(pattern)¶

Fait correspondre ce chemin avec le motif (glob pattern) fourni. Renvoie True si la correspondance a réussi, False sinon.

Si pattern est relatif, le chemin peut être soit relatif, soit absolu, et la correspondance est faite à partir de la droite :

>>> PurePath('a/b.py').match('*.py')
True
>>> PurePath('/a/b/c.py').match('b/*.py')
True
>>> PurePath('/a/b/c.py').match('a/*.py')
False

Si pattern est absolu, le chemin doit être absolu, et la correspondance doit être totale avec le chemin :

>>> PurePath('/a.py').match('/*.py')
True
>>> PurePath('a/b.py').match('/*.py')
False

Comme avec les autres méthodes, la casse est prise en compte :

>>> PureWindowsPath('b.py').match('*.PY')
True

PurePath.relative_to(*other)¶

Calcule une version du chemin en relatif au chemin représenté par other. Si c’est impossible, ValueError est levée :

>>> p = PurePosixPath('/etc/passwd')
>>> p.relative_to('/')
PurePosixPath('etc/passwd')
>>> p.relative_to('/etc')
PurePosixPath('passwd')
>>> p.relative_to('/usr')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 694, in relative_to
    .format(str(self), str(formatted)))
ValueError: '/etc/passwd' does not start with '/usr'

PurePath.with_name(name)¶

Renvoie un nouveau chemin avec name changé. Si le chemin original n’a pas de nom, ValueError est levée :

>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_name('setup.py')
PureWindowsPath('c:/Downloads/setup.py')
>>> p = PureWindowsPath('c:/')
>>> p.with_name('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 751, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name

PurePath.with_suffix(suffix)¶

Return a new path with the suffix changed. If the original path doesn’t have a suffix, the new suffix is appended instead. If the suffix is an empty string, the original suffix is removed:

>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_suffix('.bz2')
PureWindowsPath('c:/Downloads/pathlib.tar.bz2')
>>> p = PureWindowsPath('README')
>>> p.with_suffix('.txt')
PureWindowsPath('README.txt')
>>> p = PureWindowsPath('README.txt')
>>> p.with_suffix('')
PureWindowsPath('README')

11.1.3. Chemins concrets¶

Les chemins concrets sont des sous-classes des chemins purs. En plus des opérations fournies par ces derniers, ils fournissent aussi des méthodes pour faire appel au système sur des objets chemin. Il y a trois façons d’instancier des chemins concrets :

class pathlib.Path(*pathsegments)¶

Une sous-classe de PurePath, cette classe représente les chemins concrets d’une famille de chemins de système de fichiers (l’instancier créé soit un PosixPath, soit un WindowsPath) :

>>> Path('setup.py')
PosixPath('setup.py')

pathsegments est spécifié de manière similaire à PurePath.

class pathlib.PosixPath(*pathsegments)¶

Une sous-classe de Path et PurePosixPath, cette classe représente les chemins concrets de systèmes de fichiers non Windows :

>>> PosixPath('/etc')
PosixPath('/etc')

pathsegments est spécifié de manière similaire à PurePath.

class pathlib.WindowsPath(*pathsegments)¶

Une sous-classe de Path et PureWindowsPath, cette classe représente les chemins concrets de systèmes de fichiers Windows :

>>> WindowsPath('c:/Program Files/')
WindowsPath('c:/Program Files')

pathsegments est spécifié de manière similaire à PurePath.

Vous ne pouvez instancier la classe de la famille qui correspond à votre système (permettre des appels au système pour des familles de chemins non compatible pourrait mener à des bogues ou à des pannes de votre application) :

>>> import os
>>> os.name
'posix'
>>> Path('setup.py')
PosixPath('setup.py')
>>> PosixPath('setup.py')
PosixPath('setup.py')
>>> WindowsPath('setup.py')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 798, in __new__
    % (cls.__name__,))
NotImplementedError: cannot instantiate 'WindowsPath' on your system

11.1.3.1. Méthodes¶

Les chemins concrets fournissent les méthodes suivantes en plus des méthodes des chemins purs. Beaucoup de ces méthodes peuvent lever OSError si un appel au système échoue (par exemple car le chemin n’existe pas) :

classmethod Path.cwd()¶

Renvoie un nouveau chemin représentant le dossier courant (comme renvoyé par os.getcwd()) :

>>> Path.cwd()
PosixPath('/home/antoine/pathlib')

classmethod Path.home()¶

Renvoie un nouveau chemin représentant le dossier d’accueil de l’utilisateur (comme renvoyé par os.path.expanduser() avec la construction ~ ) :

>>> Path.home()
PosixPath('/home/antoine')

Nouveau dans la version 3.5.

Path.stat()¶

Renvoie les informations à propos de ce chemin (de manière similaire à os.stat()). Le résultat est récupéré à chaque appel à cette méthode.

>>> p = Path('setup.py')
>>> p.stat().st_size
956
>>> p.stat().st_mtime
1327883547.852554

Path.chmod(mode)¶

Change le mode et les permissions du fichier, comme os.chmod() :

>>> p = Path('setup.py')
>>> p.stat().st_mode
33277
>>> p.chmod(0o444)
>>> p.stat().st_mode
33060

Path.exists()¶

Si le chemin pointe sur un fichier ou dossier existant :

>>> Path('.').exists()
True
>>> Path('setup.py').exists()
True
>>> Path('/etc').exists()
True
>>> Path('nonexistentfile').exists()
False

Note

Si le chemin pointe sur un lien symbolique, exists() renvoie si le lien symbolique pointe vers un fichier ou un dossier existant.

Path.expanduser()¶

Renvoie un nouveau chemin avec les résolutions des constructions ~ et ~user, comme retourné par os.path.expanduser() :

>>> p = PosixPath('~/films/Monty Python')
>>> p.expanduser()
PosixPath('/home/eric/films/Monty Python')

Nouveau dans la version 3.5.

Path.glob(pattern)¶

Globalise le pattern fourni dans le dossier représenté par ce chemin, donnant tous les fichiers correspondants (de n’importe quelle sorte) :

>>> sorted(Path('.').glob('*.py'))
[PosixPath('pathlib.py'), PosixPath('setup.py'), PosixPath('test_pathlib.py')]
>>> sorted(Path('.').glob('*/*.py'))
[PosixPath('docs/conf.py')]

Le motif « ** » signifie que « ce dossier et ses sous-dossiers, récursivement ». En d’autres mots, il active la récursivité de la globalisation :

>>> sorted(Path('.').glob('**/*.py'))
[PosixPath('build/lib/pathlib.py'),
 PosixPath('docs/conf.py'),
 PosixPath('pathlib.py'),
 PosixPath('setup.py'),
 PosixPath('test_pathlib.py')]

Note

Utiliser le motif « ** » dans de grandes arborescences de dossier peut consommer une quantité de temps démesurée.

Path.group()¶: Renvoie le nom du groupe auquel appartient le fichier. KeyError est levée si l’identifiant de groupe du fichier n’est pas trouvé dans la base de données système.

Path.is_dir()¶

Renvoie True si le chemin pointe vers un dossier (ou un lien symbolique pointant vers un dossier), False s’il pointe vers une autre sorte de fichier.