os.path — Vanliga manipuleringar av sökvägsnamn

Källkod: Lib/genericpath.py, Lib/posixpath.py (för POSIX) och Lib/ntpath.py (för Windows).

Den här modulen implementerar några användbara funktioner för sökvägsnamn. För att läsa eller skriva filer se open(), och för åtkomst till filsystemet se os-modulen. Sökvägsparametrarna kan skickas som strängar, bytes eller objekt som implementerar os.PathLike-protokollet.

Till skillnad från ett Unix-shell gör Python inga automatiska sökvägsexpansioner. Funktioner som expanduser() och expandvars() kan anropas explicit när ett program önskar shell-liknande sökvägsexpansion. (Se även modulen glob.)

Se även

Modulen pathlib erbjuder sökvägsobjekt på hög nivå.

Anteckning

Alla dessa funktioner accepterar antingen bara bytes eller bara strängobjekt som sina parametrar. Resultatet är ett objekt av samma typ om en sökväg eller ett filnamn returneras.

Anteckning

Eftersom olika operativsystem har olika konventioner för sökvägsnamn finns det flera versioner av denna modul i standardbiblioteket. Modulen os.path är alltid den sökvägsmodul som är lämplig för det operativsystem som Python körs på, och kan därför användas för lokala sökvägar. Men du kan också importera och använda de enskilda modulerna om du vill manipulera en sökväg som alltid är i ett av de olika formaten. De har alla samma gränssnitt:

  • posixpath för sökvägar i UNIX-stil

  • ntpath för sökvägar i Windows

Ändrad i version 3.8: exists(), lexists(), isdir(), isfile(), islink() och ismount() returnerar nu False istället för att skapa ett undantag för sökvägar som innehåller tecken eller byte som inte kan representeras på OS-nivå.

os.path.abspath(path)

Returnerar en normaliserad absolutiserad version av sökvägsnamnet path. På de flesta plattformar är detta likvärdigt med att anropa funktionen normpath() enligt följande: normpath(join(os.getcwd(), path)).

Ändrad i version 3.6: Accepterar en path-like object.

os.path.basename(path, /)

Returnerar basnamnet för sökvägsnamnet sökväg. Detta är det andra elementet i det par som returneras genom att skicka path till funktionen split(). Observera att resultatet av denna funktion skiljer sig från Unix basename-program; där basename för '/foo/bar/' returnerar 'bar', returnerar basename()-funktionen en tom sträng ('').

Ändrad i version 3.6: Accepterar en path-like object.

os.path.commonpath(paths)

Returnerar den längsta gemensamma undersökvägen för varje sökväg i iterationen paths. Utlöser ValueError om paths innehåller både absoluta och relativa sökvägar, om paths finns på olika enheter eller om paths är tom. Till skillnad från commonprefix() returnerar detta en giltig sökväg.

Tillagd i version 3.5.

Ändrad i version 3.6: Accepterar en sekvens av path-liknande objekt.

Ändrad i version 3.13: Alla iterabler kan nu skickas, i stället för bara sekvenser.

os.path.commonprefix(list, /)

Returnerar det längsta sökvägsprefixet (taget tecken för tecken) som är ett prefix för alla sökvägar i list. Om list är tom returneras den tomma strängen ('').

Anteckning

Denna funktion kan returnera ogiltiga sökvägar eftersom den arbetar med ett tecken i taget. För att få en giltig sökväg, se commonpath().

>>> os.path.commonprefix(['/usr/lib', '/usr/local/lib'])
'/usr/l'

>>> os.path.commonpath(['/usr/lib', '/usr/local/lib'])
'/usr'

Ändrad i version 3.6: Accepterar en path-like object.

os.path.dirname(path, /)

Returnerar katalognamnet för sökvägsnamnet sökväg. Detta är det första elementet i det par som returneras när path skickas till funktionen split().

Ändrad i version 3.6: Accepterar en path-like object.

os.path.exists(path)

Returnerar True om path hänvisar till en befintlig sökväg eller en öppen filbeskrivare. Returnerar False för brutna symboliska länkar. På vissa plattformar kan denna funktion returnera False om tillstånd inte ges för att köra os.stat() på den begärda filen, även om sökvägen fysiskt existerar.

Ändrad i version 3.3: path kan nu vara ett heltal: True returneras om det är en öppen filbeskrivare, False annars.

Ändrad i version 3.6: Accepterar en path-like object.

os.path.lexists(path)

Returnerar True om path refererar till en befintlig sökväg, inklusive brutna symboliska länkar. Motsvarar exists() på plattformar som saknar os.lstat().

Ändrad i version 3.6: Accepterar en path-like object.

os.path.expanduser(path)

På Unix och Windows returneras argumentet med en initial komponent av ~ eller ~user ersatt av den användarens hemkatalog.

På Unix ersätts en initial ~ av miljövariabeln HOME om den är inställd; annars söks den aktuella användarens hemkatalog upp i lösenordskatalogen genom den inbyggda modulen pwd. En första ~``användare söks upp direkt i lösenordskatalogen.

I Windows kommer USERPROFILE att användas om den är angiven, annars kommer en kombination av HOMEPATH och HOMEDRIVE att användas. En första ~user hanteras genom att kontrollera att den sista katalogkomponenten i den aktuella användarens hemkatalog matchar USERNAME, och ersätta den om så är fallet.

Om expansionen misslyckas eller om sökvägen inte börjar med en tilde, returneras sökvägen oförändrad.

Ändrad i version 3.6: Accepterar en path-like object.

Ändrad i version 3.8: Använder inte längre HOME på Windows.

os.path.expandvars(path)

Returnerar argumentet med miljövariablerna expanderade. Substrängar av formen $name eller ${name} ersätts av värdet på miljövariabeln name. Missbildade variabelnamn och referenser till icke-existerande variabler lämnas oförändrade.

I Windows stöds %name%-expansioner utöver $name och ${name}.

Ändrad i version 3.6: Accepterar en path-like object.

os.path.getatime(path, /)

Returnerar tiden för senaste åtkomst till sökväg. Returvärdet är ett flyttal som anger antalet sekunder sedan epoken (se modulen time). Ger OSError om filen inte finns eller är otillgänglig.

os.path.getmtime(path, /)

Returnerar tidpunkten för den senaste ändringen av sökväg. Returvärdet är ett flyttal som anger antalet sekunder sedan epoken (se modulen time). Utlöser OSError om filen inte finns eller är otillgänglig.

Ändrad i version 3.6: Accepterar en path-like object.

os.path.getctime(path, /)

Returnerar systemets ctime, som på vissa system (t.ex. Unix) är tidpunkten för den senaste metadataförändringen och på andra (t.ex. Windows) är skapelsetiden för path. Returvärdet är ett tal som anger antalet sekunder sedan epoken (se modulen time). Utlöser OSError om filen inte finns eller är otillgänglig.

Ändrad i version 3.6: Accepterar en path-like object.

os.path.getsize(path, /)

Returnerar storleken, i byte, på path. Ger OSError om filen inte finns eller är otillgänglig.

Ändrad i version 3.6: Accepterar en path-like object.

os.path.isabs(path, /)

Returnerar True om path är ett absolut sökvägsnamn. På Unix betyder det att det börjar med ett snedstreck, på Windows att det börjar med två (bak)snedstreck, eller en enhetsbokstav, kolon och (bak)snedstreck tillsammans.

Ändrad i version 3.6: Accepterar en path-like object.

Ändrad i version 3.13: I Windows returneras False om den angivna sökvägen börjar med exakt ett (bak)snedstreck.

os.path.isfile(path)

Returnerar True om sökväg är en existerande vanlig fil. Detta följer symboliska länkar, så både islink() och isfile() kan vara true för samma sökväg.

Ändrad i version 3.6: Accepterar en path-like object.

os.path.isdir(path, /)

Returnerar True om sökväg är en existerande katalog. Detta följer symboliska länkar, så både islink() och isdir() kan vara true för samma sökväg.

Ändrad i version 3.6: Accepterar en path-like object.

os.path.isjunction(path)

Returnerar True om path hänvisar till en existerande katalogpost som är en korsning. Returnerar alltid False om junctions inte stöds på den aktuella plattformen.

Tillagd i version 3.12.

Returnerar True om path refererar till en existerande katalogpost som är en symbolisk länk. Alltid False om symboliska länkar inte stöds av Pythons runtime.

Ändrad i version 3.6: Accepterar en path-like object.

os.path.ismount(path)

Returnerar True om sökvägsnamnet sökväg ä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:`{path}/..`, finns på en annan enhet än *sökväg, eller om path/.. 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. Den kan inte på ett tillförlitligt sätt upptäcka bindningar på samma filsystem. På Linux-system returnerar den alltid True för btrfs-undervolymer, även om de inte är monteringspunkter. På Windows är en enhetsbeteckning root och en delning UNC alltid monteringspunkter, och för alla andra sökvägar anropas GetVolumePathName för att se om den skiljer sig från inmatningssökvägen.

Ändrad i version 3.4: Stöd för att upptäcka monteringspunkter som inte är root i Windows har lagts till.

Ändrad i version 3.6: Accepterar en path-like object.

os.path.isdevdrive(path)

Returnerar True om sökvägsnamnet path finns på en Windows Dev Drive. En Dev Drive är optimerad för utvecklarscenarier och erbjuder snabbare prestanda för att läsa och skriva filer. Den rekommenderas för användning av källkod, tillfälliga byggkataloger, paketcacher och andra IO-intensiva operationer.

Kan ge upphov till ett fel om sökvägen är ogiltig, t.ex. om den saknar en identifierbar enhet, men returnerar False på plattformar som inte stöder Dev-enheter. Se Windows-dokumentationen för information om hur du aktiverar och skapar Dev-enheter.

Tillagd i version 3.12.

Ändrad i version 3.13: Funktionen är nu tillgänglig på alla plattformar och kommer alltid att returnera False på de plattformar som inte har stöd för Dev Drives

os.path.isreserved(path)

Returnerar True om path är ett reserverat sökvägsnamn på det aktuella systemet.

I Windows inkluderar reserverade filnamn sådana som slutar med ett mellanslag eller en punkt, sådana som innehåller kolon (t.ex. filströmmar som ”name:stream”), jokertecken (t.ex. '*?"<>'), pipe eller ASCII-kontrolltecken, samt DOS-enhetsnamn som ”NUL”, ”CON”, ”CONIN$”, ”CONOUT$”, ”AUX”, ”PRN”, ”COM1” och ”LPT1”.

Anteckning

Denna funktion approximerar regler för reserverade sökvägar på de flesta Windows-system. Dessa regler ändras över tid i olika Windows-versioner. Den här funktionen kan komma att uppdateras i framtida Python-utgåvor när ändringar av reglerna blir allmänt tillgängliga.

Tillgänglighet: Windows.

Tillagd i version 3.13.

os.path.join(path, /, *paths)

Sammanfoga ett eller flera sökvägssegment på ett intelligent sätt. Returvärdet är sammankopplingen av path och alla medlemmar av *paths, med exakt en katalogseparator efter varje icke-tom del, utom den sista. Det vill säga att resultatet bara slutar med en separator om den sista delen antingen är tom eller slutar med en separator. Om ett segment är en absolut sökväg (vilket i Windows kräver både en enhet och en rot) ignoreras alla tidigare segment och sammanfogningen fortsätter från det absoluta sökvägssegmentet.

I Windows återställs inte enheten när ett rotat sökvägssegment (t.ex. r'\foo') påträffas. Om ett segment ligger på en annan enhet eller är en absolut sökväg ignoreras alla tidigare segment och enheten återställs. Observera att eftersom det finns en aktuell katalog för varje enhet, representerar os.path.join("c:", "foo") en sökväg relativt till den aktuella katalogen på enheten C: (c:foo), inte c:\foo.

Ändrad i version 3.6: Accepterar en path-like object för path och paths.

os.path.normcase(path, /)

Normalisera versalerna i ett sökvägsnamn. I Windows konverterar du alla tecken i sökvägsnamnet till gemener och konverterar även snedstreck framåt till snedstreck bakåt. På andra operativsystem returneras sökvägen oförändrad.

Ändrad i version 3.6: Accepterar en path-like object.

os.path.normpath(path)

Normalisera ett sökvägsnamn genom att kollapsa överflödiga separatorer och referenser på högre nivåer så att A//B, A/B/, A/./B och A/foo/../B alla blir A/B. Denna strängmanipulation kan ändra betydelsen av en sökväg som innehåller symboliska länkar. I Windows konverteras snedstreck framåt till snedstreck bakåt. Använd normcase() om du vill normalisera teckenföljden.

Anteckning

På POSIX-system, i enlighet med IEEE Std 1003.1 2013 Edition; 4.13 Pathname Resolution, om ett sökvägsnamn börjar med exakt två snedstreck, kan den första komponenten efter de inledande tecknen tolkas på ett implementationsdefinierat sätt, även om mer än två inledande tecken ska behandlas som ett enda tecken.

Ändrad i version 3.6: Accepterar en path-like object.

os.path.realpath(path, /, *, strict=False)

Returnerar den kanoniska sökvägen för det angivna filnamnet och eliminerar eventuella symboliska länkar som påträffas i sökvägen (om de stöds av operativsystemet). I Windows löser denna funktion även namn i MS-DOS (även kallat 8.3) stil, t.ex. C:\\PROGRA~1 till C:\\Program Files.

Som standard utvärderas sökvägen fram till den första komponent som inte finns, som är en symlänk-loop eller vars utvärdering ger upphov till OSError. Alla sådana komponenter läggs till oförändrade till den befintliga delen av sökvägen.

Några fel som hanteras på det här sättet är ”åtkomst nekad”, ”inte en katalog” eller ”dåligt argument till intern funktion”. Den resulterande sökvägen kan alltså saknas eller vara otillgänglig, kan fortfarande innehålla länkar eller loopar och kan korsa icke-kataloger.

Detta beteende kan ändras med hjälp av nyckelordsargument:

Om strict är True, kommer det första felet som uppstår när sökvägen utvärderas att visas igen. I synnerhet FileNotFoundError om sökväg inte finns, eller ett annat OSError om den på annat sätt är otillgänglig.

Om strict är os.path.ALLOW_MISSING, kommer andra fel än FileNotFoundError att visas igen (som med strict=True). Den returnerade sökvägen kommer alltså inte att innehålla några symboliska länkar, men den namngivna filen och några av dess överordnade kataloger kan saknas.

Anteckning

Den här funktionen emulerar operativsystemets procedur för att göra en sökväg kanonisk, som skiljer sig något mellan Windows och UNIX när det gäller hur länkar och efterföljande sökvägskomponenter interagerar.

Operativsystemets API:er gör sökvägar kanoniska efter behov, så det är normalt inte nödvändigt att anropa den här funktionen.

Ändrad i version 3.6: Accepterar en path-like object.

Ändrad i version 3.8: Symboliska länkar och korsningar löses nu i Windows.

Ändrad i version 3.10: Parametern strict lades till.

Ändrad i version 3.14: Värdet ALLOW_MISSING för parametern strict har lagts till.

os.path.ALLOW_MISSING

Specialvärde som används för strict-argumentet i realpath().

Tillagd i version 3.14.

os.path.relpath(path, start=os.curdir)

Returnerar en relativ filväg till väg antingen från den aktuella katalogen eller från en valfri start-katalog. Detta är en sökvägsberäkning: filsystemet används inte för att bekräfta existensen av eller typen av sökväg eller start. I Windows genereras ValueError när sökväg och start finns på olika enheter.

start är standardvärdet för os.curdir.

Ändrad i version 3.6: Accepterar en path-like object.

os.path.samefile(path1, path2, /)

Returnerar True om båda sökvägsargumenten hänvisar till samma fil eller katalog. Detta bestäms av enhetsnumret och i-nod-numret och ger upphov till ett undantag om ett os.stat()-anrop på något av sökvägsnamnen misslyckas.

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

Ändrad i version 3.4: Windows använder nu samma implementering som alla andra plattformar.

Ändrad i version 3.6: Accepterar en path-like object.

os.path.sameopenfile(fp1, fp2)

Returnerar True om filbeskrivarna fp1 och fp2 hänvisar till samma fil.

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

Ändrad i version 3.6: Accepterar en path-like object.

os.path.samestat(stat1, stat2, /)

Returnerar True om stat-tuplerna stat1 och stat2 refererar till samma fil. Dessa strukturer kan ha returnerats av os.fstat(), os.lstat(), eller os.stat(). Denna funktion implementerar den underliggande jämförelse som används av samefile() och sameopenfile().

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

os.path.split(path, /)

Dela upp sökvägsnamnet sökväg i ett par, (huvud, svans) där svans är den sista sökvägskomponenten och huvud är allt som leder fram till den. tail-delen kommer aldrig att innehålla ett snedstreck; om path slutar med ett snedstreck kommer tail att vara tomt. Om det inte finns något snedstreck i path kommer head att vara tom. Om sökväg är tom, är både huvud och svans tomma. Efterföljande snedstreck tas bort från head om det inte är roten (endast ett eller flera snedstreck). I samtliga fall returnerar join(head, tail) en sökväg till samma plats som path (men strängarna kan skilja sig åt). Se även funktionerna dirname() och basename().

Ändrad i version 3.6: Accepterar en path-like object.

os.path.splitdrive(path, /)

Dela upp sökvägsnamnet path i ett par (drive, tail) där drive antingen är en monteringspunkt eller den tomma strängen. På system som inte använder enhetsspecifikationer kommer drive alltid att vara den tomma strängen. I samtliga fall kommer drive + tail att vara samma sak som path.

I Windows delas ett söknamn upp i enhet/UNC sharepoint och relativ sökväg.

Om sökvägen innehåller en enhetsbeteckning kommer enheten att innehålla allt till och med kolon:

>>> splitdrive("c:/dir")
("c:", "/dir")

Om sökvägen innehåller en UNC-sökväg kommer enheten att innehålla värdnamnet och share:

>>> splitdrive("//host/computer/dir")
("//host/computer", "/dir")

Ändrad i version 3.6: Accepterar en path-like object.

os.path.splitroot(path, /)

Dela upp sökvägsnamnet path i en tupel med 3 objekt (drive, root, tail) där drive är ett enhetsnamn eller en monteringspunkt, root är en sträng med separatorer efter enheten och tail är allt efter roten. Vilken som helst av dessa poster kan vara den tomma strängen. I samtliga fall kommer drive + root + tail att vara samma sak som path.

På POSIX-system är drive alltid tomt. root kan vara tomt (om path är relativ), ett enda snedstreck (om path är absolut) eller två snedstreck (implementationsdefinierat enligt IEEE Std 1003.1-2017; 4.13 Pathname Resolution.) Till exempel:

>>> splitroot('/home/sam')
('', '/', 'home/sam')
>>> splitroot('//home/sam')
('', '//', 'home/sam')
>>> splitroot('///home/sam')
('', '/', '//home/sam')

I Windows kan drive vara tomt, en enhets bokstavsnamn, en UNC-delning eller ett enhetsnamn. root kan vara tomt, ett snedstreck framåt eller ett snedstreck bakåt. Till exempel:

>>> splitroot('C:/Users/Sam')
('C:', '/', 'Users/Sam')
>>> splitroot('//Server/Share/Users/Sam')
('//Server/Share', '/', 'Users/Sam')

Tillagd i version 3.12.

os.path.splitext(path, /)

Dela upp sökvägsnamnet sökväg i ett par (rot, ext) så att rot + ext == sökväg, och tillägget, ext, är tomt eller börjar med en punkt och innehåller högst en punkt.

Om sökvägen inte innehåller något tillägg kommer ext att vara '':

>>> splitext('bar')
('bar', '')

Om sökvägen innehåller en förlängning, kommer ext att sättas till denna förlängning, inklusive den inledande punkten. Observera att tidigare perioder ignoreras:

>>> splitext('foo.bar.exe')
('foo.bar', '.exe')
>>> splitext('/foo/bar.exe')
('/foo/bar', '.exe')

Ledande perioder av den sista komponenten i sökvägen anses vara en del av roten:

>>> splitext('.cshrc')
('.cshrc', '')
>>> splitext('/foo/....jpg')
('/foo/....jpg', '')

Ändrad i version 3.6: Accepterar en path-like object.

os.path.supports_unicode_filenames

True om godtyckliga Unicode-strängar kan användas som filnamn (inom de begränsningar som gäller för filsystemet).