„pathlib“ – objektový přístup k cestě

Python Jiří Znamenáček „pathlib“ – objektový přístup k cestě 2018-03-10

Přístup k souborovému systému na základě řetězcových cest k souborům a adresářům (typicky pomocí modulů os.path a glob.glob) je značně nespolehlivý^*. Proto se v Python'u 3.4 objevil úplně nový a značně abstrahovaný objektový přístup k cestám postavený na modulu pathlib (a dalších jemu podobných starších návrzích).

^* Obzvláště Linux se svým přístupem „název souboru je (téměř) libovolná sekvence bajtů“ v tom dělá pěkný zmatek.

Z hlediska přístupu k souborovému systému je tohle rozhodně ta správnější cesta do budoucnosti, protože jinak se dříve nebo později potkáte s velmi těžko řešitelným strašidlem kódování řetězců.

Jak GvR při jeho přijetí poznamenal: "pathlib won't replace os.path immediately …, but in the long term I expect os.path to die a quiet death"

Než se na modul pathlib podíváme pořádně, ukažme si pár jednoduchých příkladů. Nejdříve základní manipulaci s cestou:

>>> from pathlib import Path # bez udání cesty jsme v akutálním adresáři '.' >>> p0 = Path() >>> p0 PosixPath('.') >>> p0.resolve() PosixPath('/tmp') # cesty se (ne)překvapivě spojují lomítky >>> p1 = p0 / 'cesta' >>> p1 PosixPath('cesta') >>> p1.resolve() PosixPath('/tmp/cesta') # přičemž stačí, aby typu „Path“ byl pouze pravý operand >>> p2 = '..' / p0 >>> p2 PosixPath('..') >>> p2.resolve() PosixPath('/') # k dispozici máme užitečné funkce >>> Path().home() PosixPath('/home/pirat')

A teď ještě pár operací s odkazem na soubor:

# soubor má nějaké vlastnosti >>> p = Path().cwd() / 'pokus.txt' >>> p PosixPath('/tmp/pokus.txt') >>> p.parts ('/', 'tmp', 'pokus.txt') >>> p.parent PosixPath('/tmp') # souboru přímo vidíme na „vnitřnosti“ (od Python'u 3.5).. >>> p.write_text('příliš žluťoučký kůň', encoding='utf-8') 20 >>> p.read_bytes() b'p\xc5\x99\xc3\xadli\xc5\xa1 \xc5\xbelu\xc5\xa5ou\xc4\x8dk\xc3\xbd k\xc5\xaf\xc5\x88' # ..a můžeme s ním i celkem libovolně nakládat >>> t = Path('tmp.txt') >>> t PosixPath('tmp.txt') >>> t.resolve() PosixPath('/tmp/tmp.txt') >>> p.rename(t) >>> p PosixPath('/tmp/pokus.txt') >>> p.exists() False >>> t PosixPath('tmp.txt') >>> t.exists() True >>> t.read_text(encoding='utf-8') 'příliš žluťoučký kůň'

Ne všechny operace jsou asi úplně průhledné, ale když nic jiného, tak se všechny odehrávají na jednom jediném objektu a ne pomocí armády funkcí v modulu os.

I když spousta metod objektu Path je (zatím) interně implementována právě voláním odpovídajících funkcí v modulu os ^_~

Z úplně nejvyššího pohledu se modul pathlib skládá z hierarchie tříd, které postupně implementují..

abstraktní operace s cestami bez vlastního vstupu/výstupu na souborový systém (tzv. Pure-cesty);
konkrétní operace s objekty na souborovém systému;

..a to obé jak ve variantách pro operační systém Windows (Windows) a Linux (Posix), tak především jednotným způsobem pro všechny podporované operační systémy:

Ve většině případů budete v reálu asi pracovat s jednou jedinou třídou, a to Path, která pro vás abstrahuje operační systém, na kterém spouštíte skript, abyste se o něj nemuseli starat.

Abstraktní cesty nemají přístup na souborový systém, takže si operacemi na nich nic náhodou nesmažete, nicméně i tak poskytují armádu metod a vlastností užitečných pro manipulaci s cestami.

PS: Základní třídou je pathlib.PurePath, která se podle aktuálního operačního systému realizuje jako PurePosixPath nebo PureWindowsPath. Obě konkrétnější třídy si můžete libovolně zavolat též, pokud z nějakého důvodu potřebujete na jedné platformě manipulovat s cestami platformy druhé.

Cesta se dá vytvořit mnoha způsoby:

přímým zadáním >>> p = PurePath('/tmp/pokus/tmp.tar.gz') >>> p PurePosixPath('/tmp/pokus/tmp.tar.gz')
pomocí operátoru /, například >>> p = PurePath('/tmp') / 'pokus' / PurePath('tmp.tar.gz') >>> p PurePosixPath('/tmp/pokus/tmp.tar.gz') # Ale pozor! >>> p = PurePath('/tmp') / '/pokus' / PurePath('tmp.tar.gz') >>> p PurePosixPath('/pokus/tmp.tar.gz')
vypsáním (libovolných) jednotlivých částí >>> p = PurePath('/tmp', 'pokus/tmp.tar.gz') >>> p PurePosixPath('/tmp/pokus/tmp.tar.gz')
složením částí pomocí dedikované funkce # jako řetězce >>> p = PurePath('/tmp').joinpath('pokus', 'tmp.tar.gz') >>> p PurePosixPath('/tmp/pokus/tmp.tar.gz') # ale i jako objekty „pathlib“ >>> p = PurePath('/tmp').joinpath('pokus', PurePath('tmp.tar.gz')) >>> p PurePosixPath('/tmp/pokus/tmp.tar.gz')

Při zadání p = PurePath('/tmp/pokus/tmp.tar.gz') (ale může se pochopitelně jednat i o adresář!) dostaneme:

jednotlivé části cesty >>> p.parts ('/', 'tmp', 'pokus', 'tmp.tar.gz')
informace o kořeni (liší se u Windows a Linuxu) >>> p.drive '' >>> p.anchor '/' >>> p.root '/'
nadřazené části cesty >>> p.parent PurePosixPath('/tmp/pokus') >>> list(p.parents) [PurePosixPath('/tmp/pokus'), PurePosixPath('/tmp'), PurePosixPath('/')]
informace o jméně souboru >>> p.name 'tmp.tar.gz' >>> p.stem 'tmp.tar' >>> p.suffix '.gz' >>> p.suffixes ['.tar', '.gz']

>>> p = PurePath('/tmp/pokus/tmp.tar.gz') >>> p.as_posix() '/tmp/pokus/tmp.tar.gz' >>> p.as_uri() 'file:///tmp/pokus/tmp.tar.gz' >>> p = PurePath('/tmp/pokus/tmp.tar.gz') >>> p.relative_to('/tmp') PurePosixPath('pokus/tmp.tar.gz') >>> p.relative_to( PurePath('/tmp') ) PurePosixPath('pokus/tmp.tar.gz')

Test proti glob-vzoru:

>>> p = PurePath('/tmp/pokus/tmp.tar.gz') >>> p.match('*.gz') True >>> p.match('tmp/*.gz') False >>> p.match('pokus/*.gz') True

Pokud má cesta root a v případě Windows i drive, je pokládána za absolutní:

>>> PurePath('/tmp/pokus/tmp.tar.gz').is_absolute() True >>> PurePath('pokus/tmp.tar.gz').is_absolute() False

PS: Na Windows mohou také existovat tzv. rezervované cesty, operace s nimiž jsou zcela nedefinované a plné vedlejších efektů. O nich se dozvíte pomocí metody is_reserved().

Následující operace vyrobí na základě existující cesty cestu s novou příponou či jménem:

>>> p = PurePath('/tmp/pokus/tmp.tar.gz') # změna přípony >>> p.with_suffix('.bz2') PurePosixPath('/tmp/pokus/tmp.tar.bz2') # změna jména >>> p.with_name('tmp.tgz') PurePosixPath('/tmp/pokus/tmp.tgz')

PS: Pokud zadaná cesta nemá jméno (tedy atribut name je prázdný řetězec), obdržíte výjimku ValueError.

Narozdíl od abstraktních mají konkrétní cesty již přístup na souborový systém, tedy operací s nimi již může docházet k jeho změnám.

PS: Podobně jako u abstraktních cest je zde základní třídou pathlib.Path, která se podle aktuálního operačního systému realizuje buď jako PosixPath nebo WindowsPath. Narozdíl od abstraktních si ale obě konkrétnější třídy nemůžete libovolně zavolat! Je povolena pouze ta, která se týká vašeho systému.

PS: Manipulace s reálnými cestami pochopitelně podléhá pravidlům příslušného operačního systému, takže sice kupříkladu můžete při vytváření souborů nastavovat jejich přístupová práva a další vlastnosti, ale pouze v tom rozsahu, jaký máte přidělený pro daný běh pythoního interpretru.

Vytvoření konkrétní cesty je úplně stejné jako vytvoření abstraktní cesty, jen nejpoužívanějším konstruktorem (a nejpoužívanějším prvkem celého modulu pathlib vůbec) je nyní třída Path:

>>> from pathlib import Path >>> p = Path('/tmp/pokus') / 'tmp.txt' >>> p PosixPath('/tmp/pokus/tmp.txt')

Všechny ostatní možné způsoby vytvoření cesty fungují samozřejmě také.

K dispozici jsou dvě pomocné funkce, jak dosáhnout na konkrétní cestu:

aktuální pracovní adresář >>> Path().cwd() PosixPath('/tmp')
uživatelův domovský adresář >>> Path().home() PosixPath('/home/pirat')

PS: Nedává asi úplně moc smysl, že tyto metody nejsou statické (zvláště home(), který se prakticky nedá změnit).

>>> from pathlib import Path as P >>> P().cwd() PosixPath('/home/pirat') >>> p = P('/tmp') >>> p PosixPath('/tmp') >>> p.cwd() PosixPath('/home/pirat') >>> P().cwd() PosixPath('/home/pirat')

Podobně máme několik funkcí k úpravě cesty na normalizovaný tvar:

expanduser() – náhrada zkratky domovského adresáře ~ za celou cestu >>> p = Path('~/tmp') >>> p PosixPath('~/tmp') >>> p.expanduser() PosixPath('/home/pirat/tmp')
resolve() – převod cesty na kanonickou (včetně náhrady symlinků a eliminace '..') >>> Path().cwd() PosixPath('/tmp') >>> p = Path('./pokus/..') >>> p PosixPath('pokus/..') >>> p.resolve() PosixPath('/tmp') Od Python'u 3.6 můžete změnou výchozího nastavení parametru strict=False na True zajistit vyhození výjimky FileNotFoundError, pokud cesta neexistuje. Pokus o zkanoničtění cesty vedoucí k nekonečné smyčce vyhodí prozměnu RuntimeError.
absolute() – převod cesty na absolutní (ovšem s ponecháním '.' a '..'!) >>> p = Path('./pokus/..') >>> p PosixPath('pokus/..') >>> p.absolute() PosixPath('/tmp/pokus/..') PS: Podle poznámek ve zdrojovém kódu tato funkce ještě není odladěna…

Existence, vlastníci, časové značky a další vlastnosti:

>>> p = Path('/tmp/pokus/tmp.txt') >>> p PosixPath('/tmp/pokus/tmp.txt') # Existuje vůbec cesta? >>> p.exists() True # vlastník a skupina >>> p.owner() 'pirat' >>> p.group() 'pirat' # vlastnosti cesty (pro symlink použijte metodu „lstat()“) # PS: výstup úmyslně zalámán a okomentován >>> p.stat() os.stat_result( # práva inode'u st_mode=33188, # číslo inode'u a zařízení, na němž se nachází st_ino=1839445, st_dev=2049, # počet odkazů na inode st_nlink=1, # ID vlastníka a skupiny st_uid=1000, st_gid=1000, # (většinou) velikost souboru v bajtech st_size=29, # čas přístupu, modifikace a změny metadat (případně vytvoření) st_atime=1520868343, st_mtime=1520868300, st_ctime=1520868300 ) # Jedná se o stejnou cestu? (lze zadat různě, třebas i řetězcem) >>> Path('pokus/tmp.txt') PosixPath('pokus/tmp.txt') >>> p.samefile( Path('pokus/tmp.txt') ) True

Většina údajů vrácených z metody Path.stat() je celkem jasných, byť občas s nějakou poznámkou:

st_mode – přístupová práva k příslušnému inodeu jako číslo; pokud preferujete spíše řetězec, je na to v modulu stat šikovná funkce jménem filemode(): >>> from stat import filemode >>> filemode(33188) '-rw-r--r--'
st_atime, st_mtime, st_ctime – popořadě čas posledního přístupu k souboru (access), jeho poslední modifikace (modification) a čas poslední změny metadat či vytvoření souboru (creation; konkértní význam je tedy závislý na platformě) v sekundách od začátku (unixové) epochy: >>> from datetime import datetime >>> datetime.fromtimestamp(1520868343) datetime.datetime(2018, 3, 12, 16, 25, 43)

Co si ale vyžaduje podrobnější vysvětlení, jsou samotné vlastnosti souboru skryté jako číslo pod parametrem st_mode:

V principu jde tedy o bitovou masku údajů o souboru (aneb každý nastavený bit hlásí nějakou vlastnost), která je – pochopitelně – z části závislá na použitém operačním systému. Více viz dokumentace k modulu stat.

Dotazy na adresáře, soubory a symbolické odkazy: >>> Path('pokus').is_dir() True >>> Path('tmp.txt').is_dir() False >>> Path('tmp.txt').is_file() True >>> Path('tmp.tar.gz').is_symlink() True
Další typy dotazů – is_block_device(), is_char_device(), is_fifo(), is_socket() .

Získání seznamu podcest aktuální cesty (tedy typicky podadresářů, souborů a symbolických odkazů v daném adresáři) zařizuje generátor iterdir():

>>> p = Path('pokus') >>> p.iterdir() <generator object Path.iterdir at 0x7f6ea0eee468> # nazvdory tomu, že se výpis tváří jako řetězce.. >>> for i in p.iterdir(): ... print(i) ... pokus/tmp.txt pokus/tmp.tar.gz # ..jde ve skutečnosti o instance příslušné třídy „Path“ >>> list( p.iterdir() ) [PosixPath('pokus/tmp.txt'), PosixPath('pokus/tmp.tar.gz')]

Tohle se zjevně mimo jiné dobře kombinuje s předchozími is_-metodami:

>>> for i in p.iterdir(): ... if i.is_file(): ... print(i) ... pokus/tmp.txt pokus/tmp.tar.gz

Pokud chceme proiterovat pouze cesty, které vyhovují nějakému vzoru, máme k dispozici další metodu – glob(). Ta reaguje na klasické „divoké znaky“ ?, * a znakové rozsahy []:

>>> p = Path('/tmp') >>> list(p.glob('pokus/*')) [PosixPath('/tmp/pokus/tmp.tar.gz'), PosixPath('/tmp/pokus/tmp.txt'), PosixPath('/tmp/pokus/2.nfo'), PosixPath('/tmp/pokus/pokus.txt'), PosixPath('/tmp/pokus/1.txt')] >>> list(p.glob('pokus/*.txt')) [PosixPath('/tmp/pokus/tmp.txt'), PosixPath('/tmp/pokus/pokus.txt'), PosixPath('/tmp/pokus/1.txt')] >>> list(p.glob('pokus/[0-9].*')) [PosixPath('/tmp/pokus/2.nfo'), PosixPath('/tmp/pokus/1.txt')] Chcete-li najít soubor/adresář s ? nebo * v názvu, stačí je zavřít do []. Výstup zalámán pro lepší čitelnost.

PS: Speciální dvojznak ** označuje aktuální adresář a rekurzivně i všechny jeho podadresáře. Varianta rglob() se pak chová jako glob() s automaticky přidaným tímto dvojznakem na začátek vzoru.

Pomocí funkce chmod() můžete změnit práva a vlastnosti odkazované cesty:

>>> p = Path('/tmp/pokus/pokus.txt') >>> p.stat().st_mode 33279 >>> oct(33279) '0o100777' >>> p.chmod(0o644) >>> p.stat().st_mode 33188 >>> oct(33188) '0o100644' Pro udání práv/vlastností můžete kromě čísel také využít příslušné konstanty z modulu stat (kombinace se zadávají klasicky binárním OŘením).

PS: Je-li cesta symbolickým odkazem, změní funkce chmod() vlastnosti odkazované cesty. Chcete-li změnit vlastnosti symbolického odkazu, použijte funkci lchmod().

Soubor (prázdný) vytvoříme klasicky unixovsky pomocí funkce touch(mode=0o666, exist_ok=True):

# Zatím je adresář prázdný.. >>> p = Path('/tmp/pokus') >>> list( p.iterdir() ) [] # ..ale teď už nebude: >>> Path('pokus.txt').touch() >>> list( p.iterdir() ) [PosixPath('/tmp/pokus/pokus.txt')] Parametr exist_ok v základním nastavení na True u existujícího souboru upraví jeho čas modifikace na aktuální, při nastavení na False vyhodí výjimku FileExistsError.

Už asi nepřekvapivě se pak soubory mažou pomocí funkce unlink():

>>> Path('pokus.txt').unlink() >>> list( p.iterdir() ) []

Zdánlivě jasná funkce pro tvorbu adresářů mkdir(mode=0o777, parents=False, exist_ok=False) se snaží chovat co nejvíce jako unixový příkaz mkdir -p, takže ve výsledku je její funkcionalita sice velmi užitečná, nicméně už zdaleka ne tak jasná. Nicméně základní použití je jednoduché:

# zadání cesty řetězcem >>> Path('test1').mkdir() # zadání cesty objektem Path() >>> Path( Path('test2') ).mkdir()

Stačí si tedy jen dobře uvědomit, že mkdir() je vlastnost cesty – volá se tudíž na objektu Path a případné parametry této funkce pouze řídí její chování.

S funkcí opačnou, totiž mazání adresářů pomocí rmdir(), je to naštěstí jednodušší – představuje-li zadaná cesta prázdný adresář, bude tento smazán, jinak dojde k výjimce:

# prázdný adresář >>> Path('test2').rmdir() # neprázdný adresář >>> Path('test1').rmdir() Traceback (most recent call last): … OSError: [Errno 39] Directory not empty: 'test1' Cestu lze opět pochopitelně zadat jak řetězcem, tak objektem typu Path.

Jelikož většina funkcí tohoto modulu jsou vlastně jenom wrappery nad odpovídajícími funkcemi modulu os, nepřekvapí tudíž, že doporučovaným nezávisle na platformě operujícím příkazem pro přejmenování cesty jest funkce replace():

# Původní cesta.. >>> p = Path('/tmp/pokus/test1') # ..a její přejmenování: >>> p.replace('test') # Objekt původní cesty už neukazuje na existující objekt.. >>> p PosixPath('/tmp/pokus/test1') >>> p.exists() False # ..protože ten už má své nové jméno: >>> Path('/tmp/pokus/test').exists() True K určení cesty se opět pochopitelně dá použít místo řetězce i přímo objekt typu Path.

PS: Tím druhým příkazem, více unixově zaměřeným, jest rename().

Ačkoli se pomocí modulu pathlib dají soubory přesouvat (prostě změníte cestu daného souboru, čímž změníte jeho umístění), nedají se kupodivu kopírovat. K tomu slouží podivně pojmenovaná funkce z modulu shutil:

shutil.copy2(ZDROJ, CÍL)

Oba parametry cesty mohou nepřekvapivě být buď Path-objekty nebo řetězce.

Chcete-li zachovat jméno souboru, stačí jako CÍL použít pouze cílový adresář. Chcete-li jméno souboru změnit (nebo tak prostě potřebujete mít napsaný kód), jako CÍL použijte celou cestu včetně (nového) jména souboru.

PS: Existuje i metoda shutil.copy() (a kromě ní ještě dvě další podobné), ale ta nekopíruje většinu metadat souboru (vlastně zkopíruje pouze jeho jméno, obsah a přístupová práva). Většinou nechcete přijít třebas o čas modifikace souboru, takže použijete spíš právě copy2(), i když to vypadá divně.

Symbolický odkaz na existující cestu vyrobíme pomocí Path(SYMLINK).symlink_to(CESTA):

# Existující cesta.. >>> list( p.iterdir() ) [PosixPath('/tmp/pokus/pokus.txt')] # ..a symlink na ni: >>> Path('pokus_sln.txt').symlink_to('pokus.txt') >>> list( p.iterdir() ) [PosixPath('/tmp/pokus/pokus_sln.txt'), PosixPath('/tmp/pokus/pokus.txt')]

PS: Plný konstruktor jest symlink_to(target, target_is_directory=False), kde parametr target_is_directory má význam pouze pod Windows (musí být nastaven na True, je-li cílem symlinku adresář).

Aneb další nekonzistentní místo komplikující psaní přenositelného kódu… Pravda, Linux tento atribut ignoruje, takže ho tam můžeme uvést vždycky, ale stejně.

Když už máme cestu připravenou jako objekt typu Path, můžeme ji téměř klasicky otevřít k práci s jejím obsahem pomocí funkce open():

>>> f = Path('pokus.txt') >>> with f.open(encoding='utf-8') as soubor: ... print( soubor.read() ) ... příliš žluťoučký kůň

Její parametry jsou od druhého dále nepřekvapivě úplně stejné jako u standardní funkce open():

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

PS: Při neudání kódování si bohužel Python klasicky doplní výchozí z aktuálního systému :-(

Kromě toho ale existují i dedikované metody pro práci s obsahem cest, a to jak v textové, tak binární variantě:

Při práci s textem máme při zápise i při čtení k dispozici možnost nastavit jak kódování (parametr encoding), tak obsluhu chyb (parametr errors). Neexistující soubor bude při zápise založen:

>>> f = Path('pokus.txt') >>> f.write_text('příliš žluťoučký kůň', encoding='utf-8') 20 >>> f.read_text() 'příliš žluťoučký kůň' Plné konstruktory tedy jsou: Path.write_text(data, encoding=None, errors=None) a Path.read_text(encoding=None, errors=None) .

A opět – při neudání kódování si bohužel Python klasicky doplní výchozí z aktuálního systému. Jinak funkce write_text() při zápise vrací počet zapsaných znaků.

Při práci s bajty se žádné kódování neřeší, takže prostě jen zapisujeme a čteme bajtové řetězce, jinak je vše stejné:

>>> f = Path('pokus.nfo') >>> f.write_bytes(b'ahoj') 4 >>> f.read_bytes() b'ahoj'

A stejně tak funkce write_bytes() při zápise vrací počet zapsaných bajtů.