pathlib — Objektorienterade sökvägar i filsystemet

Tillagd i version 3.4.

Källkod: Lib/pathlib/

---

Denna modul erbjuder klasser som representerar filsystemvägar med semantik som är lämplig för olika operativsystem. Vägklasser delas in i rena vägar, som tillhandahåller rent beräkningsmässiga operationer utan I/O, och konkreta vägar, som ärver från rena vägar men också tillhandahåller I/O-operationer.

Om du aldrig har använt den här modulen tidigare eller bara är osäker på vilken klass som är rätt för din uppgift, är Path troligen vad du behöver. Den instansierar en concrete path för den plattform som koden körs på.

Rena vägar är användbara i vissa specialfall, t.ex:

1. Om du vill manipulera Windows-sökvägar på en Unix-maskin (eller vice versa). Du kan inte instansiera en WindowsPath när du kör på Unix, men du kan instansiera PureWindowsPath.

2. Du vill se till att din kod bara manipulerar sökvägar utan att faktiskt komma åt operativsystemet. I det här fallet kan det vara användbart att instansiera en av de rena klasserna eftersom de helt enkelt inte har några OS-åtkomstoperationer.

Se även

PEP 428: Pathlib-modulen – objektorienterade sökvägar i filsystemet.

Se även

För lågnivåhantering av sökvägar för strängar kan du också använda modulen os.path.

Grundläggande användning

Importera huvudklassen:

>>> from pathlib import Path

Listning av underkataloger:

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

Listar Python-källfiler i detta katalogträd:

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

Navigera inuti ett katalogträd:

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

Fråga om egenskaper för sökvägen:

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

Öppna en fil:

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

Undantag

exception pathlib.UnsupportedOperation

Ett undantag som ärver NotImplementedError och som uppstår när en åtgärd som inte stöds anropas på ett sökvägsobjekt.

Tillagd i version 3.13.

Rena vägar

Rena sökvägsobjekt tillhandahåller sökvägshanteringsoperationer som faktiskt inte har åtkomst till ett filsystem. Det finns tre sätt att komma åt dessa klasser, som vi också kallar flavours:

class pathlib.PurePath(*pathsegments)

En generisk klass som representerar systemets sökvägssmak (instansiering av den skapar antingen en PurePosixPath eller en PureWindowsPath):

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

Varje element i pathsegments kan vara antingen en sträng som representerar ett vägsegment eller ett objekt som implementerar os.PathLike-gränssnittet där __fspath__()-metoden returnerar en sträng, t.ex. ett annat vägobjekt:

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

När pathsegments är tomt antas den aktuella katalogen:

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

Om ett segment är en absolut sökväg ignoreras alla tidigare segment (som os.path.join()):

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

I Windows återställs inte enheten när ett rotat relativt sökvägssegment (t.ex. r'\foo') påträffas:

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

Felaktiga snedstreck och enkla prickar kollapsar, men inte dubbla prickar ('..') och inledande dubbla snedstreck ('//'), eftersom detta av olika skäl (t.ex. symboliska länkar, UNC-sökvägar) skulle ändra sökvägens betydelse:

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

(ett naivt tillvägagångssätt skulle göra PurePosixPath('foo/../bar') likvärdig med PurePosixPath('bar'), vilket är fel om foo är en symbolisk länk till en annan katalog)

Rena sökvägsobjekt implementerar gränssnittet os.PathLike, vilket gör att de kan användas överallt där gränssnittet accepteras.

Ändrad i version 3.6: Lagt till stöd för gränssnittet os.PathLike.

class pathlib.PurePosixPath(*pathsegments)

Denna sökvägssmak är en underklass till PurePath och representerar sökvägar som inte är Windows-filsystem:

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

pathsegments specificeras på liknande sätt som PurePath.

class pathlib.PureWindowsPath(*pathsegments)

Denna sökvägssmak är en underklass till PurePath och representerar sökvägar i Windows filsystem, inklusive UNC-sökvägar:

>>> PureWindowsPath('c:/', 'Users', 'Ximénez')
PureWindowsPath('c:/Users/Ximénez')
>>> PureWindowsPath('//server/share/file')
PureWindowsPath('//server/share/file')

pathsegments specificeras på liknande sätt som PurePath.

Oavsett vilket system du kör på kan du instansiera alla dessa klasser, eftersom de inte tillhandahåller någon operation som gör systemanrop.

Allmänna egenskaper

Sökvägar är oföränderliga och hashable. Sökvägar av samma smak är jämförbara och ordningsbara. Dessa egenskaper respekterar smakens semantik för case-folding:

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

Banor med olika smak jämför ojämlikt och kan inte beställas:

>>> 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'

Operatorer

Slash-operatorn hjälper till att skapa underordnade sökvägar, som os.path.join(). Om argumentet är en absolut sökväg ignoreras den föregående sökvägen. I Windows återställs inte enheten när argumentet är en rotad relativ sökväg (t.ex. r'\foo'):

>>> p = PurePath('/etc')
>>> p
PurePosixPath('/etc')
>>> p / 'init.d' / 'apache2'
PurePosixPath('/etc/init.d/apache2')
>>> q = PurePath('bin')
>>> '/usr' / q
PurePosixPath('/usr/bin')
>>> p / '/an_absolute_path'
PurePosixPath('/an_absolute_path')
>>> PureWindowsPath('c:/Windows', '/Program Files')
PureWindowsPath('c:/Program Files')

Ett sökvägsobjekt kan användas var som helst där ett objekt som implementerar os.PathLike accepteras:

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

Strängrepresentationen av en sökväg är själva den råa filsystemssökvägen (i ursprunglig form, t.ex. med bindestreck under Windows), som du kan skicka till alla funktioner som tar emot en filväg som en sträng:

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

På samma sätt ger anrop av bytes på en sökväg den råa filsystemssökvägen som ett bytesobjekt, kodat med os.fsencode():

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

Anteckning

Att anropa bytes är endast rekommenderat under Unix. Under Windows är unicode-formen den kanoniska representationen av sökvägar i filsystemet.

Åtkomst till enskilda delar

För att komma åt de enskilda ”delarna” (komponenterna) i en sökväg använder du följande egenskap:

PurePath.parts

En tupel som ger tillgång till sökvägens olika komponenter:

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

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

(notera hur enheten och den lokala roten är omgrupperade i en enda del)

Metoder och egenskaper

Pure paths tillhandahåller följande metoder och egenskaper:

PurePath.parser

Implementeringen av modulen os.path som används för lågnivåanalys och sammanfogning av sökvägar: antingen posixpath eller ntpath.

Tillagd i version 3.13.

PurePath.drive

En sträng som representerar enhetens bokstav eller namn, om sådan finns:

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

UNC-delar betraktas också som enheter:

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

PurePath.root

En sträng som representerar den (lokala eller globala) roten, om någon:

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

UNC-aktier har alltid en root:

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

Om sökvägen börjar med mer än två på varandra följande snedstreck, PurePosixPath kollapsar dem:

>>> PurePosixPath('//etc').root
'//'
>>> PurePosixPath('///etc').root
'/'
>>> PurePosixPath('////etc').root
'/'

Anteckning

Detta beteende överensstämmer med The Open Group Base Specifications Issue 6, paragraf 4.11 Pathname Resolution:

”Ett sökvägsnamn som börjar med två på varandra följande snedstreck kan tolkas på ett sätt som definieras av implementationen, även om mer än två inledande snedstreck ska behandlas som ett enda snedstreck.”

PurePath.anchor

Sammankopplingen av enheten och roten:

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

PurePath.parents

En oföränderlig sekvens som ger tillgång till logiska förfäder till sökvägen:

>>> 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:/')

Ändrad i version 3.10: Parent-sekvensen stöder nu slices och negativa indexvärden.

PurePath.parent

Den logiska föräldern till sökvägen:

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

Du kan inte gå förbi ett ankare, eller en tom väg:

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

Anteckning

Detta är en rent lexikal operation, därav följande beteende:

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

Om du vill gå en godtycklig filsystemssökväg uppåt rekommenderas att du först anropar Path.resolve() för att lösa upp symlänkar och eliminera "..."-komponenter.

PurePath.name

En sträng som representerar den slutliga sökvägskomponenten, exklusive enheten och roten, om sådana finns:

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

Namn på UNC-enheter räknas inte som:

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

PurePath.suffix

Den sista punktseparerade delen av den slutliga komponenten, om sådan finns:

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

Detta kallas vanligen filtillägget.

Ändrad i version 3.14: En enda punkt (”.”) anses vara ett giltigt suffix.

PurePath.suffixes

En lista över sökvägens suffix, ofta kallade filtillägg:

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

Ändrad i version 3.14: En enda punkt (”.”) anses vara ett giltigt suffix.

PurePath.stem

Den sista komponenten i sökvägen, utan suffixet:

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

PurePath.as_posix()

Returnerar en strängrepresentation av sökvägen med snedstreck (/):

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

PurePath.is_absolute()

Returnerar om sökvägen är absolut eller inte. En sökväg anses vara absolut om den har både en rot och (om smaken tillåter det) en drive:

>>> 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_relative_to(other)

Returnerar om den här sökvägen är relativ till den andra sökvägen eller inte.

>>> p = PurePath('/etc/passwd')
>>> p.is_relative_to('/etc')
True
>>> p.is_relative_to('/usr')
False

Denna metod är strängbaserad; den har varken åtkomst till filsystemet eller behandlar ”..”-segment speciellt. Följande kod är likvärdig:

>>> u = PurePath('/usr')
>>> u == p or u in p.parents
False

Tillagd i version 3.9.

Deprecated since version 3.12, removed in version 3.14: Att ange ytterligare argument är inte aktuellt; om de anges sammanfogas de med other.

PurePath.is_reserved()

Med PureWindowsPath returneras True om sökvägen anses vara reserverad under Windows, annars False. Med PurePosixPath returneras alltid False.

Ändrad i version 3.13: Windows-sökvägsnamn som innehåller ett kolon eller slutar med en punkt eller ett mellanslag betraktas som reserverade. UNC-sökvägar kan vara reserverade.

Deprecated since version 3.13, will be removed in version 3.15: Denna metod är föråldrad; använd os.path.isreserved() för att upptäcka reserverade sökvägar i Windows.

PurePath.joinpath(*pathsegments)

Att anropa denna metod motsvarar att kombinera sökvägen med vart och ett av de angivna sökvägssegmenten i tur och ordning:

>>> 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.full_match(pattern, *, case_sensitive=None)

Matchar denna sökväg mot det angivna mönstret i glob-stil. Returnerar True om matchningen lyckas, annars False. Till exempel:

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

Se även

Mönster språk dokumentation.

Som med andra metoder följer skiftlägeskänsligheten plattformens standardvärden:

>>> PurePosixPath('b.py').full_match('*.PY')
False
>>> PureWindowsPath('b.py').full_match('*.PY')
True

Sätt case_sensitive till True eller False för att åsidosätta detta beteende.

Tillagd i version 3.13.

PurePath.match(pattern, *, case_sensitive=None)

Matchar denna sökväg mot det angivna icke-rekursiva mönstret i glob-stil. Returnerar True om matchningen är lyckad, False annars.

Den här metoden liknar full_match(), men tomma mönster tillåts inte (ValueError tas upp), det rekursiva jokertecknet ”**” stöds inte (det fungerar som icke-rekursivt ”*”), och om ett relativt mönster anges görs matchningen från höger:

>>> 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

Ändrad i version 3.12: Parametern pattern accepterar en path-like object.

Ändrad i version 3.12: Parametern case_sensitive har lagts till.

PurePath.relative_to(other, walk_up=False)

Beräkna en version av den här sökvägen i förhållande till den sökväg som representeras av other. Om det är omöjligt, ValueError tas upp:

>>> 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 941, in relative_to
    raise ValueError(error_message.format(str(self), str(formatted)))
ValueError: '/etc/passwd' is not in the subpath of '/usr' OR one path is relative and the other is absolute.

När walk_up är false (standard) måste sökvägen börja med other. När argumentet är true kan .. poster läggas till för att bilda den relativa sökvägen. I alla andra fall, t.ex. sökvägar som refererar till olika enheter, visas ValueError.:

>>> p.relative_to('/usr', walk_up=True)
PurePosixPath('../etc/passwd')
>>> p.relative_to('foo', walk_up=True)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "pathlib.py", line 941, in relative_to
    raise ValueError(error_message.format(str(self), str(formatted)))
ValueError: '/etc/passwd' is not on the same drive as 'foo' OR one path is relative and the other is absolute.

Varning

Denna funktion är en del av PurePath och arbetar med strängar. Den kontrollerar inte och har inte åtkomst till den underliggande filstrukturen. Detta kan påverka alternativet walk_up eftersom det förutsätter att det inte finns några symlänkar i sökvägen; anropa resolve() först om det behövs för att lösa symlänkar.

Ändrad i version 3.12: Parametern walk_up har lagts till (det gamla beteendet är detsamma som walk_up=False).

Deprecated since version 3.12, removed in version 3.14: Att ange ytterligare positionella argument är inte aktuellt; om de anges sammanfogas de med other.

PurePath.with_name(name)

Returnerar en ny sökväg med name ändrat. Om den ursprungliga sökvägen inte har något namn, uppstår ValueError:

>>> 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_stem(stem)

Returnerar en ny sökväg med stem ändrad. Om den ursprungliga sökvägen inte har något namn, uppstår ValueError:

>>> p = PureWindowsPath('c:/Downloads/draft.txt')
>>> p.with_stem('final')
PureWindowsPath('c:/Downloads/final.txt')
>>> p = PureWindowsPath('c:/Downloads/pathlib.tar.gz')
>>> p.with_stem('lib')
PureWindowsPath('c:/Downloads/lib.gz')
>>> p = PureWindowsPath('c:/')
>>> p.with_stem('')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 861, in with_stem
    return self.with_name(stem + self.suffix)
  File "/home/antoine/cpython/default/Lib/pathlib.py", line 851, in with_name
    raise ValueError("%r has an empty name" % (self,))
ValueError: PureWindowsPath('c:/') has an empty name

Tillagd i version 3.9.

PurePath.with_suffix(suffix)

Returnerar en ny sökväg med suffix ändrat. Om den ursprungliga sökvägen inte har något suffix läggs det nya suffixet till istället. Om suffix är en tom sträng tas det ursprungliga suffixet bort:

>>> 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')

Ändrad i version 3.14: En enda punkt (”.”) anses vara ett giltigt suffix. I tidigare versioner gavs ValueError om en enda punkt angavs.

PurePath.with_segments(*pathsegments)

Skapar ett nytt sökvägsobjekt av samma typ genom att kombinera de angivna sökvägssegmenten. Denna metod anropas när en härledd sökväg skapas, t.ex. från parent och relative_to(). Subklasser kan åsidosätta denna metod för att skicka information till härledda sökvägar, till exempel:

from pathlib import PurePosixPath

klass MyPath(PurePosixPath):
    def __init__(self, *vägsegment, session_id):
        super().__init__(*vägsegment)
        self.session_id = session_id

    def with_segments(self, *sökvägssegment):
        return type(self)(*sökvägssegment, session_id=self.session_id)

etc = MyPath('/etc', session_id=42)
hosts = etc / 'hosts'
print(hosts.session_id) # 42

Tillagd i version 3.12.

Betongvägar

Konkreta sökvägar är subklasser av de rena sökvägsklasserna. Förutom de operationer som tillhandahålls av de senare, tillhandahåller de också metoder för att göra systemanrop på sökvägsobjekt. Det finns tre sätt att instansiera konkreta sökvägar:

class pathlib.Path(*pathsegments)

Denna klass är en underklass till PurePath och representerar konkreta sökvägar av systemets sökvägssmak (genom att instansiera den skapas antingen en PosixPath eller en WindowsPath):

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

pathsegments specificeras på liknande sätt som PurePath.

class pathlib.PosixPath(*pathsegments)

Denna klass är en underklass till Path och PurePosixPath och representerar konkreta sökvägar till filsystem som inte är Windows:

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

pathsegments specificeras på liknande sätt som PurePath.

Ändrad i version 3.13: Utlöser UnsupportedOperation på Windows. I tidigare versioner gavs istället NotImplementedError.

class pathlib.WindowsPath(*pathsegments)

Denna klass är en underklass till Path och PureWindowsPath och representerar konkreta sökvägar i Windows filsystem:

>>> WindowsPath('c:/', 'Users', 'Ximénez')
WindowsPath('c:/Users/Ximénez')

pathsegments specificeras på liknande sätt som PurePath.

Ändrad i version 3.13: Utlöser UnsupportedOperation på icke-Windows plattformar. I tidigare versioner gavs istället NotImplementedError.

Du kan bara instansiera den klassvariant som motsvarar ditt system (om du tillåter systemanrop på icke-kompatibla klassvarianter kan det leda till buggar eller fel i din applikation):

>>> 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__,))
UnsupportedOperation: cannot instantiate 'WindowsPath' on your system

Vissa konkreta sökvägsmetoder kan ge upphov till ett OSError om ett systemanrop misslyckas (t.ex. för att sökvägen inte finns).

Parsning och generering av URI:er

Konkreta sökvägsobjekt kan skapas från, och representeras som, ’file’ URI:er som överensstämmer med RFC 8089.

Anteckning

Fil-URI:er är inte portabla mellan maskiner med olika filsystemskodningar.

classmethod Path.from_uri(uri)

Returnerar ett nytt sökvägsobjekt från parsning av en ”file”-URI. Till exempel:

>>> p = Path.from_uri('file:///etc/hosts')
PosixPath('/etc/hosts')

I Windows kan DOS-enhets- och UNC-sökvägar tolkas från URI:er:

>>> p = Path.from_uri('file:///c:/windows')
WindowsPath('c:/windows')
>>> p = Path.from_uri('file://server/share')
WindowsPath('//server/share')

Flera olika varianter stöds:

>>> p = Path.from_uri('file:////server/share')
WindowsPath('//server/share')
>>> p = Path.from_uri('file://///server/share')
WindowsPath('//server/share')
>>> p = Path.from_uri('file:c:/windows')
WindowsPath('c:/windows')
>>> p = Path.from_uri('file:/c|/windows')
WindowsPath('c:/windows')

ValueError uppstår om URI:n inte börjar med file:, eller om den tolkade sökvägen inte är absolut.

Tillagd i version 3.13.

Ändrad i version 3.14: URL-auktoriteten kasseras om den matchar det lokala värdnamnet. I annat fall, om auktoriteten inte är tom eller localhost, returneras en UNC-sökväg på Windows (som tidigare), och på andra plattformar genereras ett ValueError.

Path.as_uri()

Representera sökvägen som en ’file’ URI. ValueError uppstår om sökvägen inte är absolut.

>>> p = PosixPath('/etc/passwd')
>>> p.as_uri()
'file:///etc/passwd'
>>> p = WindowsPath('c:/Windows')
>>> p.as_uri()
'file:///c:/Windows'

Deprecated since version 3.14, will be removed in version 3.19: Att anropa denna metod från PurePath istället för Path är möjligt men föråldrat. Metodens användning av os.fsencode() gör den strikt oren.

Utvidgning och upplösning av banor

classmethod Path.home()

Returnerar ett nytt sökvägsobjekt som representerar användarens hemkatalog (som returneras av os.path.expanduser() med ~-konstruktionen). Om hemkatalogen inte kan lösas ut kommer RuntimeError att visas.

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

Tillagd i version 3.5.

Path.expanduser()

Returnerar en ny sökväg med utökade ~ och ~user konstruktioner, som returneras av os.path.expanduser(). Om en hemkatalog inte kan lösas, uppstår RuntimeError.

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

Tillagd i version 3.5.

classmethod Path.cwd()

Returnerar ett nytt sökvägsobjekt som representerar den aktuella katalogen (som returneras av os.getcwd()):

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

Path.absolute()

Gör sökvägen absolut, utan normalisering eller lösning av symlänkar. Returnerar ett nytt sökvägsobjekt:

>>> p = Path('tests')
>>> p
PosixPath('tests')
>>> p.absolute()
PosixPath('/home/antoine/pathlib/tests')

Path.resolve(strict=False)

Gör sökvägen absolut och löser eventuella symlänkar. Ett nytt sökvägsobjekt returneras:

>>> p = Path()
>>> p
PosixPath('.')
>>> p.resolve()
PosixPath('/home/antoine/pathlib')

”..”-komponenter elimineras också (detta är den enda metoden som gör det):

>>> p = Path('docs/../setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')

Om en sökväg inte finns eller om en symlänkslinga påträffas, och strict är True, genereras OSError. Om strict är False löses sökvägen upp så långt det är möjligt och eventuella rester läggs till utan att kontrollera om den existerar.

Ändrad i version 3.6: Parametern strict har lagts till (beteendet före 3.6 är strikt).

Ändrad i version 3.13: Symlink-loopar behandlas som andra fel: OSError aktiveras i strikt läge och inget undantag aktiveras i icke-strikt läge. I tidigare versioner utlöses RuntimeError oavsett värdet på strict.

Path.readlink()

Returnera sökvägen som den symboliska länken pekar på (som returneras av os.readlink()):

>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.readlink()
PosixPath('setup.py')

Tillagd i version 3.9.

Ändrad i version 3.13: Utlöser UnsupportedOperation om os.readlink() inte är tillgänglig. I tidigare versioner gavs NotImplementedError.

Förfrågan om filtyp och status

Ändrad i version 3.8: exists(), is_dir(), is_file(), is_mount(), is_symlink(), is_block_device(), is_char_device(), is_fifo(), is_socket() returnerar nu False istället för att skapa ett undantag för sökvägar som innehåller tecken som inte kan representeras på OS-nivå.

Ändrad i version 3.14: Metoderna ovan returnerar nu False istället för att ge upphov till något OSError-undantag från operativsystemet. I tidigare versioner har vissa typer av OSError-undantag uppstått, medan andra har undertryckts. Det nya beteendet är förenligt med os.path.exists(), os.path.isdir(), etc. Använd stat() för att hämta filstatus utan att undertrycka undantag.

Path.stat(*, follow_symlinks=True)

Returnerar ett os.stat_result-objekt som innehåller information om den här sökvägen, som os.stat(). Resultatet söks upp vid varje anrop till denna metod.

Den här metoden följer normalt symlinks; för att stata en symlink lägg till argumentet follow_symlinks=False, eller använd lstat().

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

Ändrad i version 3.10: Parametern follow_symlinks har lagts till.

Path.lstat()

Som Path.stat(), men om sökvägen pekar på en symbolisk länk returneras den symboliska länkens information i stället för målets.

Path.exists(*, follow_symlinks=True)

Returnerar True om sökvägen pekar på en befintlig fil eller katalog. False returneras om sökvägen är ogiltig, otillgänglig eller saknas. Använd Path.stat() för att skilja mellan dessa fall.

Denna metod följer normalt symlinks; för att kontrollera om en symlink existerar, lägg till argumentet follow_symlinks=False.

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

Ändrad i version 3.12: Parametern follow_symlinks har lagts till.

Path.is_file(*, follow_symlinks=True)

Returnerar True om sökvägen pekar på en vanlig fil. False returneras om sökvägen är ogiltig, otillgänglig eller saknas, eller om den pekar på något annat än en vanlig fil. Använd Path.stat() för att skilja mellan dessa fall.

Denna metod följer normalt symlänkar; för att utesluta symlänkar, lägg till argumentet follow_symlinks=False.

Ändrad i version 3.13: Parametern follow_symlinks har lagts till.

Path.is_dir(*, follow_symlinks=True)

Returnerar True om sökvägen pekar på en katalog. False returneras om sökvägen är ogiltig, otillgänglig eller saknas, eller om den pekar på något annat än en katalog. Använd Path.stat() för att skilja mellan dessa fall.

Den här metoden följer normalt symlinks; om du vill utesluta symlinks till kataloger lägger du till argumentet follow_symlinks=False.

Ändrad i version 3.13: Parametern follow_symlinks har lagts till.

Path.is_symlink()

Returnerar True om sökvägen pekar på en symbolisk länk, även om symbollänken är bruten. False returneras om sökvägen är ogiltig, otillgänglig eller saknas, eller om den pekar på något annat än en symbolisk länk. Använd Path.stat() för att skilja mellan dessa fall.

Path.is_junction()

Returnerar True om sökvägen pekar på en korsning och False för alla andra typer av filer. För närvarande stöder endast Windows junctions.

Tillagd i version 3.12.

Path.is_mount()

Returnerar True om sökvägen är en mount point: en punkt i ett filsystem där ett annat filsystem har monterats. På POSIX kontrollerar funktionen om sökväg*s förälder, :file:`sökväg/..`, finns på en annan enhet än *sökväg, eller om sökväg/.. och sökväg pekar på samma i-nod på samma enhet — detta bör upptäcka monteringspunkter för alla Unix- och POSIX-varianter. I Windows anses en monteringspunkt vara en enhetsbokstav root (t.ex. c:\), en UNC-delning (t.ex. \server\share) eller en monterad filsystemkatalog.

Tillagd i version 3.7.

Ändrad i version 3.12: Stöd för Windows har lagts till.

Path.is_socket()

Returnerar True om sökvägen pekar på en Unix-socket. False returneras om sökvägen är ogiltig, otillgänglig eller saknas, eller om den pekar på något annat än en Unix-socket. Använd Path.stat() för att skilja mellan dessa fall.

Path.is_fifo()

Returnerar True om sökvägen pekar på en FIFO. False returneras om sökvägen är ogiltig, otillgänglig eller saknas, eller om den pekar på något annat än en FIFO. Använd Path.stat() för att skilja mellan dessa fall.

Path.is_block_device()

Returnerar True om sökvägen pekar på en blockenhet. False returneras om sökvägen är ogiltig, otillgänglig eller saknas, eller om den pekar på något annat än en blockenhet. Använd Path.stat() för att skilja mellan dessa fall.

Path.is_char_device()

Returnerar True om sökvägen pekar på en teckenenhet. False returneras om sökvägen är ogiltig, otillgänglig eller saknas, eller om den pekar på något annat än en teckenenhet. Använd Path.stat() för att skilja mellan dessa fall.

Path.samefile(other_path)

Returnerar om den här sökvägen pekar på samma fil som other_path, som kan vara antingen ett Path-objekt eller en sträng. Semantiken liknar os.path.samefile() och os.path.samestat().

Ett OSError kan uppstå om någon av filerna av någon anledning inte går att komma åt.

>>> p = Path('spam')
>>> q = Path('eggs')
>>> p.samefile(q)
False
>>> p.samefile('spam')
True

Tillagd i version 3.5.

Path.info

Ett PathInfo-objekt som stöder frågor om filtyp. Objektet exponerar metoder som cachar sina resultat, vilket kan bidra till att minska antalet systemanrop som behövs när man byter filtyp. Till exempel:

>>> p = Path('src')
>>> if p.info.is_symlink():
...     print('symlink')
... elif p.info.is_dir():
...     print('directory')
... elif p.info.exists():
...     print('something else')
... else:
...     print('not found')
...
directory

Om sökvägen genererades från Path.iterdir() initieras detta attribut med information om filtypen som erhållits genom att skanna den överordnade katalogen. Enbart åtkomst till Path.info utför inte några filsystemfrågor.

För att hämta aktuell information är det bäst att anropa Path.is_dir(), is_file() och is_symlink() snarare än metoder för detta attribut. Det finns inget sätt att återställa cachen; istället kan du skapa ett nytt sökvägsobjekt med en tom infocache via p = Path(p).

Tillagd i version 3.14.

Läsa och skriva filer

Path.open(mode='r', buffering=-1, encoding=None, errors=None, newline=None)

Öppna den fil som sökvägen pekar på, på samma sätt som den inbyggda funktionen open() gör:

>>> p = Path('setup.py')
>>> with p.open() as f:
...     f.readline()
...
'#!/usr/bin/env python3\n'

Path.read_text(encoding=None, errors=None, newline=None)

Returnera det avkodade innehållet i den fil som pekas ut som en sträng:

>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'

Filen öppnas och stängs sedan. De valfria parametrarna har samma betydelse som i open().

Tillagd i version 3.5.

Ändrad i version 3.13: Parametern newline har lagts till.

Path.read_bytes()

Returnera det binära innehållet i den fil som pekas ut som ett bytesobjekt:

>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'

Tillagd i version 3.5.

Path.write_text(data, encoding=None, errors=None, newline=None)

Öppna den fil som pekas ut i textläge, skriv data till den och stäng filen:

>>> p = Path('my_text_file')
>>> p.write_text('Text file contents')
18
>>> p.read_text()
'Text file contents'

En befintlig fil med samma namn skrivs över. De valfria parametrarna har samma betydelse som i open().

Tillagd i version 3.5.

Ändrad i version 3.10: Parametern newline har lagts till.

Path.write_bytes(data)

Öppna den fil som pekas ut i bytesläge, skriv data till den och stäng filen:

>>> p = Path('my_binary_file')
>>> p.write_bytes(b'Binary file contents')
20
>>> p.read_bytes()
b'Binary file contents'

En befintlig fil med samma namn skrivs över.

Tillagd i version 3.5.

Läsa kataloger

Path.iterdir()

När sökvägen pekar på en katalog, ger sökvägen objekt av kataloginnehållet:

>>> p = Path('docs')
>>> for child in p.iterdir(): child
...
PosixPath('docs/conf.py')
PosixPath('docs/_templates')
PosixPath('docs/make.bat')
PosixPath('docs/index.rst')
PosixPath('docs/_build')
PosixPath('docs/_static')
PosixPath('docs/Makefile')

Barnen ges i godtycklig ordning, och de speciella posterna '.' och '..' inkluderas inte. Om en fil tas bort från eller läggs till i katalogen efter att iteratorn har skapats, är det ospecificerat om ett sökvägsobjekt för den filen inkluderas.

Om sökvägen inte är en katalog eller på annat sätt är otillgänglig, uppstår OSError.

Path.glob(pattern, *, case_sensitive=None, recurse_symlinks=False)

Globalisera det angivna relativa mönstret i katalogen som representeras av denna sökväg, vilket ger alla matchande filer (av alla slag):

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

Se även

Mönster språk dokumentation.

Som standard, eller när det enda nyckelordsargumentet case_sensitive är inställt på None, matchar den här metoden sökvägar med hjälp av plattformsspecifika regler för skiftlägeskodning: vanligtvis skiftlägeskänsligt på POSIX och skiftlägesokänsligt på Windows. Ställ in case_sensitive till True eller False för att åsidosätta detta beteende.

Som standard, eller när det enda nyckelordsargumentet recurse_symlinks är inställt på False, följer den här metoden symolänkar utom när jokertecken ”**” expanderas. Ställ in recurse_symlinks till True för att alltid följa symboliska länkar.

Utlöser en auditing event pathlib.Path.glob med argumenten self, pattern.

Ändrad i version 3.12: Parametern case_sensitive har lagts till.

Ändrad i version 3.13: Parametern recurse_symlinks har lagts till.

Ändrad i version 3.13: Parametern pattern accepterar en path-like object.

Ändrad i version 3.13: Alla OSError-undantag som uppstår vid skanning av filsystemet undertrycks. I tidigare versioner undertrycks sådana undantag i många fall, men inte i alla.

Path.rglob(pattern, *, case_sensitive=None, recurse_symlinks=False)

Globera det givna relativa mönstret rekursivt. Detta är som att anropa Path.glob() med ”**/” tillagt framför mönstret.

Se även

Mönster språk och Path.glob() dokumentation.

Utlöser en auditing event pathlib.Path.rglob med argumenten self, pattern.

Ändrad i version 3.12: Parametern case_sensitive har lagts till.

Ändrad i version 3.13: Parametern recurse_symlinks har lagts till.

Ändrad i version 3.13: Parametern pattern accepterar en path-like object.

Path.walk(top_down=True, on_error=None, follow_symlinks=False)

Generera filnamnen i ett katalogträd genom att gå igenom trädet antingen uppifrån och ner eller nerifrån och upp.

För varje katalog i katalogträdet med rot i self (inklusive self men exklusive ’.’ och ’…’) ger metoden en 3-tupel av (dirpath, dirnames, filenames).

dirpath är en Sökväg till den katalog som för närvarande gås igenom, dirnames är en lista med strängar för namnen på underkataloger i dirpath (exklusive '.' och '..'), och filenames är en lista med strängar för namnen på de filer som inte finns i katalogen i dirpath. För att få en fullständig sökväg (som börjar med self) till en fil eller katalog i dirpath, gör dirpath / name. Huruvida listorna är sorterade eller inte är beroende av filsystemet.

Om det valfria argumentet top_down är true (vilket är standard) genereras trippeln för en katalog före tripplarna för någon av dess underkataloger (kataloger gås igenom uppifrån och ned). Om top_down är false genereras trippeln för en katalog efter tripplarna för alla dess underkataloger (kataloger gås igenom nedifrån och upp). Oavsett värdet på top_down hämtas listan med underkataloger innan tripplarna för katalogen och dess underkataloger gås igenom.

När top_down är true kan anroparen ändra dirnames-listan på plats (till exempel med del eller slice assignment), och Path.walk() kommer bara att söka i de underkataloger vars namn finns kvar i dirnames. Detta kan användas för att begränsa sökningen, eller för att införa en specifik besöksordning, eller till och med för att informera Path.walk() om kataloger som anroparen skapar eller byter namn på innan den återupptar Path.walk() igen. Att ändra dirnames när top_down är false har ingen effekt på beteendet hos Path.walk() eftersom katalogerna i dirnames redan har skapats när dirnames överlämnas till den som anropar.

Som standard ignoreras fel från os.scandir(). Om det valfria argumentet on_error anges bör det vara en callable; den kommer att anropas med ett argument, en OSError-instans. Anropsobjektet kan hantera felet för att fortsätta vandringen eller ta upp det igen för att stoppa vandringen. Observera att filnamnet är tillgängligt som attributet filename i undantagsobjektet.

Som standard följer Path.walk() inte symboliska länkar, utan lägger istället till dem i listan filnamn. Ange follow_symlinks till true för att lösa upp symboliska länkar och placera dem i dirnames och filenames på lämpligt sätt för deras mål, och följaktligen besöka kataloger som symboliska länkar pekar på (där detta stöds).

Anteckning

Tänk på att om follow_symlinks sätts till true kan det leda till oändlig rekursion om en länk pekar på en överordnad katalog till sig själv. Path.walk() håller inte reda på vilka kataloger den redan har besökt.

Anteckning

Path.walk() förutsätter att de kataloger den går igenom inte ändras under körningen. Om till exempel en katalog från dirnames har ersatts med en symlänk och follow_symlinks är false, kommer Path.walk() ändå att försöka gå ner i den. För att förhindra ett sådant beteende ska du ta bort kataloger från dirnames på lämpligt sätt.

Anteckning

Till skillnad från os.walk() listar Path.walk() symlänkar till kataloger i filnamn om follow_symlinks är false.

I det här exemplet visas antalet byte som används av alla filer i varje katalog, samtidigt som katalogerna __pycache__ ignoreras:

from pathlib import Path
for root, dirs, files in Path("cpython/Lib/concurrent").walk(on_error=print):
  print(
      root,
      "consumes",
      sum((root / file).stat().st_size for file in files),
      "bytes in",
      len(files),
      "non-directory files"
  )
  if '__pycache__' in dirs:
        dirs.remove('__pycache__')

Nästa exempel är en enkel implementation av shutil.rmtree(). Att gå igenom trädet nerifrån och upp är nödvändigt eftersom rmdir() inte tillåter att en katalog tas bort innan den är tom:

# Ta bort allt som går att nå från katalogen "top".
# FÖRSIKTIGHET: Detta är farligt! Till exempel, om top == Path('/'),
# kan det radera alla dina filer.
for root, dirs, files in top.walk(top_down=False):
    för namn i filer:
        (rot / namn).unlink()
    för namn i dirs:
        (rot / namn).rmdir()

Tillagd i version 3.12.

Skapa filer och kataloger

Path.touch(mode=0o666, exist_ok=True)

Skapa en fil på den angivna sökvägen. Om mode anges kombineras det med processens umask-värde för att bestämma filens läge och åtkomstflaggor. Om filen redan finns, lyckas funktionen när exist_ok är sant (och dess modifieringstid uppdateras till aktuell tid), annars uppstår FileExistsError.

Se även

Metoderna open(), write_text() och write_bytes() används ofta för att skapa filer.

Path.mkdir(mode=0o777, parents=False, exist_ok=False)

Skapa en ny katalog på den angivna sökvägen. Om mode anges kombineras det med processens umask-värde för att bestämma filläge och åtkomstflaggor. Om sökvägen redan finns kommer FileExistsError att visas.

Om parents är true, skapas alla saknade föräldrar till den här sökvägen vid behov; de skapas med standardbehörigheter utan att mode beaktas (efterliknar POSIX-kommandot mkdir -p).

Om parents är false (standard), orsakar en saknad förälder FileNotFoundError.

Om exist_ok är false (standard) kommer FileExistsError att uppstå om målkatalogen redan existerar.

Om exist_ok är sant kommer FileExistsError inte att uppstå om inte den angivna sökvägen redan finns i filsystemet och inte är en katalog (samma beteende som POSIX-kommandot mkdir -p).

Ändrad i version 3.5: Parametern exist_ok har lagts till.

Path.symlink_to(target, target_is_directory=False)

Gör den här sökvägen till en symbolisk länk som pekar på target.

I Windows representerar en symlänk antingen en fil eller en katalog, och den flyttas inte dynamiskt till målet. Om målet finns kommer typen av symlänk att skapas så att den matchar. I annat fall skapas symbollänken som en katalog om target_is_directory är sant eller som en filsymlänk (standard) i annat fall. På icke-Windows-plattformar ignoreras target_is_directory.

>>> p = Path('mylink')
>>> p.symlink_to('setup.py')
>>> p.resolve()
PosixPath('/home/antoine/pathlib/setup.py')
>>> p.stat().st_size
956
>>> p.lstat().st_size
8

Anteckning

Ordningen på argumenten (länk, mål) är den omvända mot os.symlink().

Ändrad i version 3.13: Utlöser UnsupportedOperation om os.symlink() inte är tillgänglig. I tidigare versioner gavs NotImplementedError.

Path.hardlink_to(target)

Gör den här sökvägen till en hård länk till samma fil som target.

Anteckning

Ordningen på argumenten (länk, mål) är den omvända mot os.link().

Tillagd i version 3.10.

Ändrad i version 3.13: Visar UnsupportedOperation om os.link() inte är tillgänglig. I tidigare versioner gavs NotImplementedError.

Kopiera, flytta och radera

Path.copy(target, *, follow_symlinks=True, preserve_metadata=False)

Kopierar detta fil- eller katalogträd till det angivna målet och returnerar en ny Path-instans som pekar på målet.

Om källan är en fil kommer målet att ersättas om det är en befintlig fil. Om källan är en symbolisk länk och follow_symlinks är true (standard) kopieras den symboliska länkens mål. Annars återskapas symlänken på destinationen.

Om preserve_metadata är false (standard) är det bara katalogstrukturer och fildata som garanterat kopieras. Ange preserve_metadata till true för att säkerställa att fil- och katalogbehörigheter, flaggor, senaste åtkomst- och ändringstider samt utökade attribut kopieras där så stöds. Detta argument har ingen effekt vid kopiering av filer i Windows (där metadata alltid bevaras).

Anteckning

Om operativsystemet och filsystemet stöder den här metoden utförs en lättviktskopiering, där datablock endast kopieras när de ändras. Detta är känt som copy-on-write.

Tillagd i version 3.14.

Path.copy_into(target_dir, *, follow_symlinks=True, preserve_metadata=False)

Kopierar detta fil- eller katalogträd till den angivna target_dir, som bör vara en befintlig katalog. Andra argument hanteras identiskt med Path.copy(). Returnerar en ny Path-instans som pekar på kopian.

Tillagd i version 3.14.

Path.rename(target)

Byt namn på denna fil eller katalog till det angivna target och returnera en ny Path-instans som pekar på target. På Unix, om target finns och är en fil, kommer den att ersättas tyst om användaren har behörighet. På Windows, om target existerar, kommer FileExistsError att uppstå. target kan vara antingen en sträng eller ett annat sökvägsobjekt:

>>> p = Path('foo')
>>> p.open('w').write('some text')
9
>>> target = Path('bar')
>>> p.rename(target)
PosixPath('bar')
>>> target.open().read()
'some text'

Målsökvägen kan vara absolut eller relativ. Relativa sökvägar tolkas i förhållande till den aktuella arbetskatalogen, inte katalogen för Path-objektet.

Den implementeras i form av os.rename() och ger samma garantier.

Ändrad i version 3.8: Lagt till returvärde, returnerar den nya Path-instansen.

Path.replace(target)

Byt namn på denna fil eller katalog till det angivna target, och returnera en ny Path-instans som pekar på target. Om target pekar på en befintlig fil eller en tom katalog kommer den ovillkorligen att ersättas.

Målsökvägen kan vara absolut eller relativ. Relativa sökvägar tolkas i förhållande till den aktuella arbetskatalogen, inte katalogen för Path-objektet.

Ändrad i version 3.8: Lagt till returvärde, returnerar den nya Path-instansen.

Path.move(target)

Flytta detta fil- eller katalogträd till det angivna målet, och returnera en ny Path-instans som pekar på målet.

Om target inte finns kommer den att skapas. Om både den här sökvägen och target är befintliga filer, skrivs målet över. Om båda sökvägarna pekar på samma fil eller katalog, eller om target är en katalog som inte är tom, kommer OSError att skapas.

Om båda sökvägarna finns i samma filsystem utförs flytten med os.replace(). I annat fall kopieras sökvägen (med metadata och symlänkar bevarade) och raderas sedan.

Tillagd i version 3.14.

Path.move_into(target_dir)

Flyttar detta fil- eller katalogträd till den angivna target_dir, som bör vara en befintlig katalog. Returnerar en ny Path-instans som pekar på den flyttade sökvägen.

Tillagd i version 3.14.

Path.unlink(missing_ok=False)

Ta bort denna fil eller symboliska länk. Om sökvägen pekar på en katalog, använd Path.rmdir() istället.

Om missing_ok är false (standard) kommer FileNotFoundError att uppstå om sökvägen inte finns.

Om missing_ok är true, ignoreras FileNotFoundError (samma beteende som POSIX-kommandot rm -f).

Ändrad i version 3.8: Parametern missing_ok har lagts till.

Path.rmdir()

Ta bort den här katalogen. Katalogen måste vara tom.

Behörigheter och ägande

Path.owner(*, follow_symlinks=True)

Returnerar namnet på den användare som äger filen. KeyError uppstår om filens användaridentifierare (UID) inte finns i systemdatabasen.

Denna metod följer normalt symlänkar; för att få ägaren till symlänken, lägg till argumentet follow_symlinks=False.

Ändrad i version 3.13: Utlöser UnsupportedOperation om modulen pwd inte är tillgänglig. I tidigare versioner gavs NotImplementedError.

Ändrad i version 3.13: Parametern follow_symlinks har lagts till.

Path.group(*, follow_symlinks=True)

Returnerar namnet på den grupp som äger filen. KeyError uppstår om filens gruppidentifierare (GID) inte finns i systemdatabasen.

Denna metod följer normalt symlänkar; för att få gruppen i symbollänken, lägg till argumentet follow_symlinks=False.

Ändrad i version 3.13: Utlöser UnsupportedOperation om modulen grp inte är tillgänglig. I tidigare versioner gavs NotImplementedError.

Ändrad i version 3.13: Parametern follow_symlinks har lagts till.

Path.chmod(mode, *, follow_symlinks=True)

Ändra filens läge och behörigheter, som os.chmod().

Den här metoden följer normalt symlänkar. Vissa Unix-versioner stöder ändring av behörigheter på själva symbollänken; på dessa plattformar kan du lägga till argumentet follow_symlinks=False, eller använda lchmod().

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

Ändrad i version 3.10: Parametern follow_symlinks har lagts till.

Path.lchmod(mode)

Som Path.chmod(), men om sökvägen pekar på en symbolisk länk ändras den symboliska länkens läge i stället för målets.

Mönster språk

Följande jokertecken stöds i mönster för full_match(), glob() och rglob():

** (hela segmentet)

Matchar valfritt antal fil- eller katalogsegment, inklusive noll.

* (hela segmentet)

Matchar ett fil- eller katalogsegment.

* (del av ett segment)

Matchar valfritt antal tecken utan separator, inklusive noll.

?

Matchar ett tecken utan separator.

[seq]

Matchar ett tecken i seq, där seq är en sekvens av tecken. Uttryck för intervall stöds, t.ex. [a-z] matchar alla gemena ASCII-bokstäver. Flera intervall kan kombineras: [a-zA-Z0-9_] matchar alla ASCII-bokstäver, siffror eller understreck.

[!seq]

Matchar ett tecken som inte finns med i seq, där seq följer samma regler som ovan.

För en bokstavlig matchning omsluter du metatecknen inom parentes. Till exempel matchar "[?]" tecknet "?".

Jokertecknet ”**” möjliggör rekursiv globbing. Några exempel:

Mönster	Betydelse
”**/*”	Varje väg med minst ett segment.
”**/*.py”	Alla sökvägar med ett slutsegment som slutar på ”.py”.
”tillgångar/**”	Alla sökvägar som börjar med ”assets/”.
”tillgångar/**/*”	Alla sökvägar som börjar med ”assets/”, utom själva ”assets/”.

Anteckning

Om du använder jokertecknet ”**” besöks alla kataloger i trädet. Stora katalogträd kan ta lång tid att söka igenom.

Ändrad i version 3.13: Globbing med ett mönster som slutar med ”**” returnerar både filer och kataloger. I tidigare versioner returnerades endast kataloger.

I Path.glob() och rglob() kan ett efterföljande snedstreck läggas till i mönstret för att endast matcha kataloger.

Ändrad i version 3.11: Globbing med ett mönster som slutar med en komponentavgränsare för sökvägsnamn (sep eller altsep) returnerar endast kataloger.

Jämförelse med glob-modulen

De mönster som accepteras och de resultat som genereras av Path.glob() och Path.rglob() skiljer sig något från dem som genereras av modulen glob:

1. Filer som börjar med en punkt är inte speciella i pathlib. Detta är som att skicka include_hidden=True till glob.glob().

2. ”**”-mönsterkomponenter är alltid rekursiva i pathlib. Detta är som att skicka recursive=True till glob.glob().

3. ”**”-mönsterkomponenter följer inte symlinks som standard i pathlib. Detta beteende har ingen motsvarighet i glob.glob(), men du kan skicka recurse_symlinks=True till Path.glob() för ett kompatibelt beteende.

4. Liksom alla PurePath- och Path-objekt innehåller de värden som returneras från Path.glob() och Path.rglob() inte efterföljande snedstreck.

5. De värden som returneras från pathlibs path.glob() och path.rglob() inkluderar path som prefix, till skillnad från resultaten från glob.glob(root_dir=path).

6. De värden som returneras från pathlibs path.glob() och path.rglob() kan innehålla path själv, till exempel vid globbing av ”**”, medan resultaten från glob.glob(root_dir=path) aldrig innehåller en tom sträng som skulle motsvara path.

Jämförelse med modulerna os och os.path

pathlib implementerar sökvägsoperationer med hjälp av PurePath och Path-objekt, och därför sägs den vara objektorienterad. Å andra sidan tillhandahåller modulerna os och os.path funktioner som arbetar med lågnivåobjekten str och bytes, vilket är ett mer procedurinriktat tillvägagångssätt. Vissa användare anser att den objektorienterade stilen är mer läsbar.

Många funktioner i os och os.path stöder bytes-sökvägar och sökvägar relativt katalogbeskrivare. Dessa funktioner är inte tillgängliga i pathlib.

Pythons typer str och bytes, och delar av modulerna os och os.path, är skrivna i C och är mycket snabba. pathlib är skrivet i ren Python och är ofta långsammare, men sällan tillräckligt långsamt för att det ska spela någon roll.

pathlibs normalisering av sökvägar är något mer åsiktsbaserad och konsekvent än os.path. Till exempel, medan os.path.abspath() eliminerar ”..”-segment från en sökväg, vilket kan ändra dess betydelse om symlinks är inblandade, bevarar Path.absolute() dessa segment för större säkerhet.

pathlibs normalisering av sökvägar kan göra den olämplig för vissa applikationer:

1. pathlib normaliserar Path("my_folder/") till Path("my_folder"), vilket ändrar en sökvägs betydelse när den tillhandahålls till olika API:er för operativsystem och kommandoradsverktyg. I synnerhet kan avsaknaden av en efterföljande separator göra det möjligt att lösa sökvägen som antingen en fil eller en katalog, snarare än bara en katalog.

2. pathlib normaliserar Path("./my_program") till Path("my_program"), vilket ändrar en sökvägs betydelse när den används som sökväg för körbara program, t.ex. i ett skal eller när en underordnad process startas. Specifikt kan avsaknaden av en separator i sökvägen tvinga den att letas upp i PATH i stället för i den aktuella katalogen.

Som en följd av dessa skillnader är pathlib inte en direkt ersättning för os.path.

Motsvarande verktyg

Nedan finns en tabell som mappar olika os-funktioner till deras motsvarande PurePath/Path-ekvivalenter.

os och os.path	pathlib
os.sökväg.dirnamn()	PurePath.förälder
os.sökväg.basnamn()	PurePath.namn
os.sökväg.splitext()	PurePath.stem, PurePath.suffix
os.sökväg.join()	PurePath.joinpath()
os.path.isabs`()	PurePath.is_absolute()
os.path.relpath()	PurePath.relative_to() [1]
os.path.expanduser()	Path.expanduser() [2]
os.path.realpath()	Path.resolve()
os.path.abspath()	Sökväg.absolut() [3]
os.path.exists()	Sökväg.finns()
os.path.isfile()	Path.is_file()
os.sökväg.isdir()	Path.is_dir()
os.sökväg.islink()	Sökväg.is_symlänk()
os.path.isjunction()	Sökväg.is_junction()
os.sökväg.ismount()	Path.is_mount()
os.sökväg.samefile()	Sökväg.samefile()
os.getcwd()	Sökväg.cwd()
os.stat()	Sökväg.stat()
os.lstat()	Sökväg.lstat()
os.listdir()	Sökväg.iterdir()
os.walk()	Path.walk() [4]
os.mkdir(), os.makedirs()	Sökväg.mkdir()
os.länk()	Sökväg.hårdlänk_till()
os.symlänk()	Path.symlink_to()
os.readlink()	Sökväg.läslänk()
os.rename()	Path.rename()
os.replace()	Sökväg.ersätt()
os.remove(), os.unlink()	Path.unlink()
os.rmdir()	Sökväg.rmdir()
os.chmod()	Sökväg.chmod()
os.lchmod()	Sökväg.lchmod()

Fotnoter

[1]

os.path.relpath() anropar abspath() för att göra sökvägar absoluta och ta bort ”..”-delar, medan PurePath.relative_to() är en lexikal operation som ger upphov till ValueError när dess ingångars ankare skiljer sig åt (t.ex. om en sökväg är absolut och den andra relativ)

[2]

os.path.expanduser() returnerar sökvägen oförändrad om hemkatalogen inte kan lösas, medan Path.expanduser() ger upphov till RuntimeError.

[3]

os.path.abspath() tar bort ”..”-komponenter utan att lösa symlänkar, vilket kan ändra sökvägens betydelse, medan Path.absolute() lämnar kvar alla ”..”-komponenter i sökvägen.

[4]

os.walk() följer alltid symlänkar när sökvägar kategoriseras i katalognamn och filnamn, medan Path.walk() kategoriserar alla symlänkar i filnamn när follow_symlinks är false (standard)

Protokoll

Modulen pathlib.types tillhandahåller typer för statisk typkontroll.

Tillagd i version 3.14.

class pathlib.types.PathInfo

En typing.Protocol som beskriver attributet Path.info. Implementationer kan returnera cachade resultat från sina metoder.

exists(*, follow_symlinks=True)

Returnerar True om sökvägen är en befintlig fil eller katalog, eller någon annan typ av fil; returnerar False om sökvägen inte finns.

Om follow_symlinks är False, returneras True för symlinks utan att kontrollera om deras mål existerar.

is_dir(*, follow_symlinks=True)

Returnerar True om sökvägen är en katalog, eller en symbolisk länk som pekar på en katalog; returnerar False om sökvägen är (eller pekar på) någon annan typ av fil, eller om den inte finns.

Om follow_symlinks är False, returneras True endast om sökvägen är en katalog (utan att följa symlinks); returneras False om sökvägen är någon annan typ av fil, eller om den inte finns.

is_file(*, follow_symlinks=True)

Returnerar True om sökvägen är en fil eller en symbolisk länk som pekar på en fil; returnerar False om sökvägen är (eller pekar på) en katalog eller annan icke-fil, eller om den inte finns.

Om follow_symlinks är False, returneras True endast om sökvägen är en fil (utan att följa symlinks); returneras False om sökvägen är en katalog eller annan icke-fil, eller om den inte finns.

is_symlink()

Returnerar True om sökvägen är en symbolisk länk (även om den är bruten); returnerar False om sökvägen är en katalog eller någon annan typ av fil, eller om den inte finns.