shutil — Filoperationer på hög nivå

Källkod: Lib/shutil.py

---

Modulen shutil erbjuder ett antal funktioner på hög nivå för filer och samlingar av filer. I synnerhet finns funktioner som stöder kopiering och borttagning av filer. För operationer på enskilda filer, se även modulen os.

Varning

Inte ens filkopieringsfunktionerna på högre nivå (shutil.copy(), shutil.copy2()) kan kopiera alla filmetadata.

På POSIX-plattformar innebär detta att filägare och grupp försvinner, liksom ACL:er. På Mac OS används inte resursgaffeln och andra metadata. Det innebär att resurser går förlorade och att filtyp och skaparkod inte blir korrekta. På Windows kopieras inte filägare, ACL:er och alternativa dataströmmar.

Katalog- och filoperationer

shutil.copyfileobj(fsrc, fdst[, length])

Kopierar innehållet i filliknande objekt fsrc till det filliknande objektet fdst. Heltalet length, om det anges, är buffertstorleken. Ett negativt length-värde innebär att data kopieras utan att källdata loopas i bitar; som standard läses data i bitar för att undvika okontrollerad minnesförbrukning. Observera att om den aktuella filpositionen för fsrc-objektet inte är 0, kommer endast innehållet från den aktuella filpositionen till slutet av filen att kopieras.

copyfileobj() kommer inte att garantera att målströmmen har tömts när kopieringen är klar. Om du vill läsa från destinationen när kopieringen är klar (t.ex. läsa innehållet i en temporär fil som har kopierats från en HTTP-ström), måste du se till att du har anropat flush() eller close() på det filliknande objektet innan du försöker läsa destinationsfilen.

shutil.copyfile(src, dst, *, follow_symlinks=True)

Kopiera innehållet (inga metadata) i filen med namnet src till en fil med namnet dst och returnera dst på effektivast möjliga sätt. src och dst är sökvägsliknande objekt eller sökvägsnamn angivna som strängar.

dst måste vara det fullständiga målfilsnamnet; se copy() för en kopiering som accepterar en målkatalogsökväg. Om src och dst anger samma fil, uppstår SameFileError.

Destinationsplatsen måste vara skrivbar, annars kommer ett OSError undantag att uppstå. Om dst redan finns kommer den att ersättas. Specialfiler som tecken- eller blockenheter och pipes kan inte kopieras med den här funktionen.

Om follow_symlinks är false och src är en symbolisk länk, skapas en ny symbolisk länk i stället för att kopiera filen som src pekar på.

Utlöser en auditing event shutil.copyfile med argumenten src, dst.

Ändrad i version 3.3: IOError brukade visas istället för OSError. Argumentet follow_symlinks lades till. Returnerar nu dst.

Ändrad i version 3.4: Utlös SameFileError istället för Error. Eftersom den förra är en subklass av den senare är denna ändring bakåtkompatibel.

Ändrad i version 3.8: Plattformsspecifika syscalls för snabbkopiering kan användas internt för att kopiera filen mer effektivt. Se avsnittet Plattformsberoende effektiva kopieringsoperationer.

exception shutil.SameFileError

Detta undantag uppstår om källan och destinationen i copyfile() är samma fil.

Tillagd i version 3.4.

shutil.copymode(src, dst, *, follow_symlinks=True)

Kopiera behörighetsbitarna från src till dst. Filens innehåll, ägare och grupp påverkas inte. src och dst är sökvägsliknande objekt eller sökvägsnamn angivna som strängar. Om follow_symlinks är false och både src och dst är symboliska länkar, kommer copymode() att försöka ändra läget för dst själv (snarare än filen den pekar på). Denna funktion är inte tillgänglig på alla plattformar; se copystat() för mer information. Om copymode() inte kan modifiera symboliska länkar på den lokala plattformen, och den ombeds att göra det, kommer den inte att göra någonting och returnera.

Utlöser en auditing event shutil.copymode med argumenten src, dst.

Ändrad i version 3.3: Lagt till argumentet follow_symlinks.

shutil.copystat(src, dst, *, follow_symlinks=True)

Kopierar behörighetsbitar, senaste åtkomsttid, senaste ändringstid och flaggor från src till dst. På Linux kopierar copystat() även de ”utökade attributen” där så är möjligt. Filinnehåll, ägare och grupp påverkas inte. src och dst är sökvägsliknande objekt eller sökvägsnamn angivna som strängar.

Om follow_symlinks är false, och src och dst båda hänvisar till symboliska länkar, kommer copystat() att arbeta med de symboliska länkarna själva snarare än med de filer som de symboliska länkarna hänvisar till - läsa informationen från den symboliska länken src och skriva informationen till den symboliska länken dst.

Anteckning

Det är inte alla plattformar som ger möjlighet att undersöka och ändra symboliska länkar. Python själv kan berätta vilken funktionalitet som är lokalt tillgänglig.

• Om os.chmod in os.supports_follow_symlinks är True, kan copystat() ändra behörighetsbitarna för en symbolisk länk.

• Om os.utime in os.supports_follow_symlinks är True, kan copystat() ändra den senaste åtkomst- och ändringstiden för en symbolisk länk.

• Om os.chflags in os.supports_follow_symlinks är True kan copystat() ändra flaggorna för en symbolisk länk. (os.chflags är inte tillgänglig på alla plattformar)

På plattformar där en del av eller all denna funktionalitet inte är tillgänglig, kommer copystat() att kopiera allt den kan när den ombeds att ändra en symbolisk länk. copystat() returnerar aldrig fel.

Se os.supports_follow_symlinks för mer information.

Utlöser en auditing event shutil.copystat med argumenten src, dst.

Ändrad i version 3.3: Argumentet follow_symlinks och stöd för Linux utökade attribut har lagts till.

shutil.copy(src, dst, *, follow_symlinks=True)

Kopierar filen src till filen eller katalogen dst. src och dst bör vara path-liknande objekt eller strängar. Om dst anger en katalog kommer filen att kopieras till dst med hjälp av basfilnamnet från src. Om dst anger en fil som redan finns kommer den att ersättas. Returnerar sökvägen till den nyskapade filen.

Om follow_symlinks är false och src är en symbolisk länk kommer dst att skapas som en symbolisk länk. Om follow_symlinks är true och src är en symbolisk länk, blir dst en kopia av den fil som src hänvisar till.

copy() kopierar filinformationen och filens behörighetsläge (se os.chmod()). Andra metadata, t.ex. filens skapelse- och ändringstid, bevaras inte. Om du vill bevara alla filmetadata från originalet använder du istället copy2().

Utlöser en auditing event shutil.copyfile med argumenten src, dst.

Utlöser en auditing event shutil.copymode med argumenten src, dst.

Ändrad i version 3.3: Lagt till argumentet follow_symlinks. Returnerar nu sökvägen till den nyskapade filen.

Ändrad i version 3.8: Plattformsspecifika syscalls för snabbkopiering kan användas internt för att kopiera filen mer effektivt. Se avsnittet Plattformsberoende effektiva kopieringsoperationer.

shutil.copy2(src, dst, *, follow_symlinks=True)

Identisk med copy() förutom att copy2() också försöker bevara metadata för filer.

När follow_symlinks är false och src är en symbolisk länk försöker copy2() att kopiera alla metadata från den symboliska länken src till den nyskapade symboliska länken dst. Denna funktion är dock inte tillgänglig på alla plattformar. På plattformar där hela eller delar av denna funktionalitet inte är tillgänglig kommer copy2() att bevara alla metadata den kan; copy2() ger aldrig upphov till ett undantag för att den inte kan bevara filmetadata.

copy2() använder copystat() för att kopiera filens metadata. Se copystat() för mer information om plattformsstöd för modifiering av metadata för symboliska länkar.

Utlöser en auditing event shutil.copyfile med argumenten src, dst.

Utlöser en auditing event shutil.copystat med argumenten src, dst.

Ändrad i version 3.3: Lagt till follow_symlinks-argument, försök att kopiera utökade filsystemattribut också (för närvarande endast Linux). Returnerar nu sökvägen till den nyskapade filen.

Ändrad i version 3.8: Plattformsspecifika syscalls för snabbkopiering kan användas internt för att kopiera filen mer effektivt. Se avsnittet Plattformsberoende effektiva kopieringsoperationer.

shutil.ignore_patterns(*patterns)

Denna fabriksfunktion skapar en funktion som kan användas som en anropbar funktion för copytree()’s ignore-argument, och ignorerar filer och kataloger som matchar ett av de mönster i glob-stil som anges. Se exemplet nedan.

shutil.copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False)

Kopiera rekursivt ett helt katalogträd med rot i src till en katalog med namnet dst och returnera destinationskatalogen. Alla mellanliggande kataloger som behövs för att innehålla dst kommer också att skapas som standard.

Behörigheter och tider för kataloger kopieras med copystat(), enskilda filer kopieras med copy2().

Om symlinks är true representeras symboliska länkar i källträdet som symboliska länkar i det nya trädet och metadata för de ursprungliga länkarna kopieras så långt som plattformen tillåter; om false eller utelämnas kopieras innehållet och metadata för de länkade filerna till det nya trädet.

När symlinks är false, om filen som symlänken pekar på inte finns, kommer ett undantag att läggas till i listan över fel som tas upp i ett Error-undantag i slutet av kopieringsprocessen. Du kan sätta den valfria flaggan ignore_dangling_symlinks till true om du vill tysta detta undantag. Observera att det här alternativet inte har någon effekt på plattformar som inte stöder os.symlink().

Om ignore anges, måste det vara en anropbar funktion som får som argument den katalog som besöks av copytree(), och en lista över dess innehåll, som returneras av os.listdir(). Eftersom copytree() anropas rekursivt, kommer anropet ignore att anropas en gång för varje katalog som kopieras. Anropet måste returnera en sekvens av katalog- och filnamn i förhållande till den aktuella katalogen (dvs. en delmängd av objekten i dess andra argument); dessa namn kommer sedan att ignoreras i kopieringsprocessen. ignore_patterns() kan användas för att skapa ett sådant anrop som ignorerar namn baserade på glob-liknande mönster.

Om ett eller flera undantag inträffar genereras ett Error med en lista över orsaker.

Om copy_function anges måste det vara en anropsbar funktion som används för att kopiera varje fil. Den kommer att anropas med källsökvägen och destinationssökvägen som argument. Som standard används copy2(), men alla funktioner som stöder samma signatur (som copy()) kan användas.

Om dirs_exist_ok är false (standard) och dst redan existerar, uppstår ett FileExistsError. Om dirs_exist_ok är true fortsätter kopieringen om den stöter på befintliga kataloger, och filer i dst-trädet skrivs över av motsvarande filer från src-trädet.

Utlöser en auditing event shutil.copytree med argumenten src, dst.

Ändrad i version 3.2: Lagt till argumentet copy_function för att kunna tillhandahålla en anpassad kopieringsfunktion. Lagt till argumentet ignore_dangling_symlinks för att dämpa fel med dinglande symlänkar när symlinks är false.

Ändrad i version 3.3: Kopiera metadata när symlinks är false. Returnerar nu dst.

Ändrad i version 3.8: Plattformsspecifika syscalls för snabbkopiering kan användas internt för att kopiera filen mer effektivt. Se avsnittet Plattformsberoende effektiva kopieringsoperationer.

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

shutil.rmtree(path, ignore_errors=False, onerror=None, *, onexc=None, dir_fd=None)

Ta bort ett helt katalogträd; path måste peka på en katalog (men inte på en symbolisk länk till en katalog). Om ignore_errors är true ignoreras fel som uppstår vid misslyckade borttagningar; om false eller utelämnas hanteras sådana fel genom att anropa en hanterare som specificeras av onexc eller onerror eller, om båda utelämnas, sprids undantag till den som anropar.

Den här funktionen kan stödja sökvägar som är relativa till katalogbeskrivare.

Anteckning

På plattformar som stöder de nödvändiga fd-baserade funktionerna används som standard en version av rmtree() som är motståndskraftig mot symlänkattacker. På andra plattformar är implementeringen av rmtree() känslig för en symlänk-attack: med rätt timing och omständigheter kan angripare manipulera symlinks i filsystemet för att radera filer som de annars inte skulle ha tillgång till. Program kan använda funktionsattributet rmtree.avoids_symlink_attacks för att avgöra vilket fall som gäller.

Om onexc anges måste det vara en callable som accepterar tre parametrar: funktion, sökväg och excinfo.

Den första parametern, function, är den funktion som orsakade undantaget; den beror på plattform och implementering. Den andra parametern, path, är det sökvägsnamn som skickas till function. Den tredje parametern, excinfo, är det undantag som uppstod. Undantag som orsakas av onexc kommer inte att fångas upp.

Den föråldrade onerror liknar onexc, förutom att den tredje parametern den tar emot är den tupel som returneras från sys.exc_info().

Se även

exempel på rmtree för ett exempel på hur man hanterar borttagningen av ett katalogträd som innehåller skrivskyddade filer.

Utlöser en auditing event shutil.rmtree med argumenten path, dir_fd.

Ändrad i version 3.3: Lagt till en version som är motståndskraftig mot symlink-attacker och som används automatiskt om plattformen stöder fd-baserade funktioner.

Ändrad i version 3.8: I Windows tas inte längre innehållet i en katalogövergång bort innan övergången tas bort.

Ändrad i version 3.11: Parametern dir_fd har lagts till.

Ändrad i version 3.12: Parametern onexc tillagd, onerror borttagen.

Ändrad i version 3.13: rmtree() ignorerar nu FileNotFoundError-undantag för alla utom sökvägen på högsta nivån. Andra undantag än OSError och underklasser till OSError sprids nu alltid till den som anropar.

rmtree.avoids_symlink_attacks

Anger om den aktuella plattformen och implementationen tillhandahåller en version av rmtree() som är motståndskraftig mot symlink-attacker. För närvarande gäller detta endast för plattformar som stöder fd-baserade funktioner för katalogåtkomst.

Tillagd i version 3.3.

shutil.move(src, dst, copy_function=copy2)

Flytta rekursivt en fil eller katalog (src) till en annan plats och returnera destinationen.

Om dst är en befintlig katalog eller en symlänk till en katalog, flyttas src till den katalogen. Målsökvägen i den katalogen får inte redan existera.

Om dst redan finns men inte är en katalog kan den komma att skrivas över beroende på os.rename() semantik.

Om destinationen finns i det aktuella filsystemet används os.rename(). Annars kopieras src till destinationen med hjälp av copy_function och tas sedan bort. Om det gäller symlinks skapas en ny symlink som pekar på målet för src som destination och src tas bort.

Om copy_function anges måste det vara en anropsbar funktion som tar två argument, src och destinationen, och som kommer att användas för att kopiera src till destinationen om os.rename() inte kan användas. Om källan är en katalog anropas copytree() som får copy_function. Standard copy_function är copy2(). Genom att använda copy() som copy_function kan flytten lyckas när det inte är möjligt att även kopiera metadata, på bekostnad av att inga metadata kopieras.

Utlöser en auditing event shutil.move med argumenten src, dst.

Ändrad i version 3.3: Lade till explicit symlänkhantering för utländska filsystem och anpassade den därmed till beteendet i GNU:s mv. Returnerar nu dst.

Ändrad i version 3.5: Lagt till nyckelordsargumentet copy_function.

Ändrad i version 3.8: Plattformsspecifika syscalls för snabbkopiering kan användas internt för att kopiera filen mer effektivt. Se avsnittet Plattformsberoende effektiva kopieringsoperationer.

Ändrad i version 3.9: Accepterar en path-like object för både src och dst.

shutil.disk_usage(path)

Returnerar diskanvändningsstatistik för den angivna sökvägen som en named tuple med attributen total, used och free, som är mängden totalt, använt och ledigt utrymme i byte. path kan vara en fil eller en katalog.

Anteckning

På Unix-filsystem måste path peka på en sökväg inom en monterad filsystemspartition. På dessa plattformar försöker CPython inte att hämta information om diskanvändning från icke monterade filsystem.

Tillagd i version 3.3.

Ändrad i version 3.8: I Windows kan path nu vara en fil eller katalog.

Tillgänglighet: Unix, Windows.

shutil.chown(path, user=None, group=None, *, dir_fd=None, follow_symlinks=True)

Ändra ägare user och/eller group för den angivna path.

user kan vara ett systemanvändarnamn eller ett uid; samma sak gäller för group. Minst ett argument krävs.

Se även os.chown(), den underliggande funktionen.

Utlöser en auditing-händelse shutil.chown med argumenten path, user, group.

Tillgänglighet: Unix.

Tillagd i version 3.3.

Ändrad i version 3.13: Parametrarna dir_fd och follow_symlinks har lagts till.

shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)

Returnerar sökvägen till en körbar fil som skulle köras om den angivna cmd anropades. Om ingen cmd skulle anropas returneras None.

mode är en behörighetsmask som skickas till os.access(), som standard avgör den om filen finns och är körbar.

path är en ”PATH-sträng” som anger de kataloger som ska sökas i, avgränsad av os.pathsep. Om ingen path anges, läses miljövariabeln PATH från os.environ, och faller tillbaka till os.defpath om den inte är inställd.

Om cmd innehåller en katalogkomponent kontrollerar which() endast den angivna sökvägen direkt och söker inte i de kataloger som anges i path eller i systemets miljövariabel PATH.

I Windows prependlas den aktuella katalogen till path om mode inte innehåller os.X_OK. När mode innehåller os.X_OK, kommer Windows API NeedCurrentDirectoryForExePathW att konsulteras för att avgöra om den aktuella katalogen ska läggas till path. För att undvika att den aktuella arbetskatalogen konsulteras för körbara filer: ställ in miljövariabeln NoDefaultCurrentDirectoryInExePath.

I Windows används även miljövariabeln PATHEXT för att lösa kommandon som kanske inte redan innehåller ett tillägg. Om du till exempel anropar shutil.which("python"), kommer which() att söka i PATHEXT för att veta att den ska leta efter python.exe i katalogerna path. Till exempel på Windows:

>>> shutil.which("python")
'C:\\Python33\\python.EXE'

Detta gäller även när cmd är en sökväg som innehåller en katalogkomponent:

>>> shutil.which("C:\\Python33\\python")
'C:\\Python33\\python.EXE'

Tillagd i version 3.3.

Ändrad i version 3.8: Typen bytes accepteras nu. Om cmd-typen är bytes, är resultattypen också bytes.

Ändrad i version 3.12: I Windows läggs inte längre den aktuella katalogen till i sökvägen om mode innehåller os.X_OK och WinAPI NeedCurrentDirectoryForExePathW(cmd) är false, annars läggs den aktuella katalogen till även om den redan finns i sökvägen; PATHEXT används nu även när cmd innehåller en katalogkomponent eller slutar med ett tillägg som finns i PATHEXT; och filnamn som inte har något tillägg kan nu hittas.

exception shutil.Error

Detta undantag samlar in undantag som uppstår under en operation med flera filer. För copytree() är undantagsargumentet en lista med 3-tuples (srcname, dstname, exception).

Plattformsberoende effektiva kopieringsoperationer

Från och med Python 3.8 kan alla funktioner som involverar en filkopiering (copyfile(), copy(), copy2(), copytree(), och move()) använda plattformsspecifika ”fast-copy” syscalls för att kopiera filen mer effektivt (se bpo-33671). ”Fast-copy” innebär att kopieringsoperationen sker i kärnan, vilket undviker användning av userspace-buffertar i Python som i ”outfd.write(infd.read())”.

På macOS används fcopyfile för att kopiera filinnehållet (inte metadata).

På Linux används os.copy_file_range() eller os.sendfile().

På Solaris används os.sendfile().

I Windows använder shutil.copyfile() en större standardbuffertstorlek (1 MiB istället för 64 KiB) och en memoryview()-baserad variant av shutil.copyfileobj() används.

Om snabbkopieringen misslyckas och inga data skrevs i målfilen kommer shutil att tyst fallbacka till att använda den mindre effektiva copyfileobj()-funktionen internt.

Ändrad i version 3.8.

Ändrad i version 3.14: Solaris använder nu os.sendfile().

Ändrad i version 3.14: Copy-on-write eller kopiering på serversidan kan användas internt via os.copy_file_range() på Linux-filsystem som stöds.

exempel på copytree

Ett exempel som använder hjälpen ignore_patterns():

from shutil import copytree, ignore_patterns

copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))

Detta kopierar allt utom .pyc-filer och filer eller kataloger vars namn börjar med tmp.

Ett annat exempel som använder ignore-argumentet för att lägga till ett loggningsanrop:

from shutil import copytree
import logging

def _logpath(path, names):
    logging.info('Working in %s', path)
    return []   # nothing will be ignored

copytree(source, destination, ignore=_logpath)

exempel på rmtree

Det här exemplet visar hur man tar bort ett katalogträd i Windows där vissa av filerna har skrivskyddad bit inställd. Det använder onexc callback för att rensa den skrivskyddade biten och göra ett nytt försök att ta bort. Eventuella efterföljande fel kommer att sprida sig.

import os, stat
import shutil

def remove_readonly(func, path, _):
    "Clear the readonly bit and reattempt the removal"
    os.chmod(path, stat.S_IWRITE)
    func(path)

shutil.rmtree(directory, onexc=remove_readonly)

Arkiveringsverksamhet

Tillagd i version 3.2.

Ändrad i version 3.5: Stöd för formatet xztar har lagts till.

Verktyg på hög nivå för att skapa och läsa komprimerade och arkiverade filer tillhandahålls också. De förlitar sig på modulerna zipfile och tarfile.

shutil.make_archive(base_name, format[, root_dir[, base_dir[, verbose[, dry_run[, owner[, group[, logger]]]]]]])

Skapa en arkivfil (t.ex. zip eller tar) och ange dess namn.

base_name är namnet på den fil som ska skapas, inklusive sökvägen, minus eventuella formatspecifika tillägg.

format är arkivformatet: ett av följande: ”zip” (om modulen zlib finns tillgänglig), ”tar”, ”gztar” (om modulen zlib finns tillgänglig), ”bztar” (om modulen bz2 finns tillgänglig), ”xztar” (om modulen lzma finns tillgänglig) eller ”zstdtar” (om modulen compression.zstd finns tillgänglig).

root_dir är en katalog som kommer att vara arkivets rotkatalog, alla sökvägar i arkivet kommer att vara relativa till den; vi brukar t.ex. chdir:a till root_dir innan vi skapar arkivet.

base_dir är den katalog där vi börjar arkivera från, dvs. base_dir kommer att vara det gemensamma prefixet för alla filer och kataloger i arkivet. base_dir måste anges i förhållande till root_dir. Se Exempel på arkivering med base_dir för hur man använder base_dir och root_dir tillsammans.

root_dir och base_dir är båda förvalda till den aktuella katalogen.

Om dry_run är true skapas inget arkiv, men de operationer som skulle ha utförts loggas i logger.

owner och group används när ett tar-arkiv skapas. Som standard används den aktuella ägaren och gruppen.

logger måste vara ett objekt som är kompatibelt med PEP 282, vanligtvis en instans av logging.Logger.

Argumentet verbose är oanvänt och föråldrat.

Utlöser en auditing-händelse shutil.make_archive med argumenten base_name, format, root_dir, base_dir.

Anteckning

Den här funktionen är inte trådsäker när anpassade arkiverare som registrerats med register_archive_format() inte stöder argumentet root_dir. I så fall ändras processens aktuella arbetskatalog tillfälligt till root_dir för att utföra arkivering.

Ändrad i version 3.8: Det moderna pax-formatet (POSIX.1-2001) används nu i stället för det äldre GNU-formatet för arkiv som skapats med format="tar".

Ändrad i version 3.10.6: Denna funktion är nu trådsäker under skapandet av standardarkiv av typen .zip och tar.

shutil.get_archive_formats()

Returnerar en lista över format som stöds för arkivering. Varje element i den returnerade sekvensen är en tupel (namn, beskrivning).

Som standard tillhandahåller shutil dessa format:

• zip: ZIP-fil (om modulen zlib är tillgänglig).

• tar: Okomprimerad tar-fil. Använder POSIX.1-2001 pax-format för nya arkiv.

• gztar: gzip’ed tar-fil (om modulen zlib är tillgänglig).

• bztar: bzip2-behandlad tar-fil (om modulen bz2 är tillgänglig).

• xztar: xz’ed tar-fil (om modulen lzma är tillgänglig).

• zstdtar: Zstandardkomprimerad tar-fil (om modulen compression.zstd är tillgänglig).

Du kan registrera nya format eller tillhandahålla din egen arkiverare för befintliga format genom att använda register_archive_format().

shutil.register_archive_format(name, function[, extra_args[, description]])

Registrera en arkiverare för formatet namn.

function är den anropbara funktion som kommer att användas för att packa upp arkiv. Anropsfunktionen tar emot base_name för filen som ska skapas, följt av base_dir (som standard är os.curdir) för att starta arkiveringen från. Ytterligare argument skickas som nyckelordsargument: owner, group, dry_run och logger (som skickas i make_archive()).

Om function har det anpassade attributet function.supports_root_dir inställt på True, skickas root_dir-argumentet som ett nyckelordsargument. Annars ändras processens aktuella arbetskatalog tillfälligt till root_dir innan function anropas. I det här fallet är make_archive() inte trådsäker.

Om extra_args anges är det en sekvens av par av (namn, värde) som kommer att användas som extra nyckelordsargument när arkiverarens anropsbarhet används.

description används av get_archive_formats() som returnerar en lista över arkivbildare. Standardvärdet är en tom sträng.

Ändrad i version 3.12: Lagt till stöd för funktioner som stöder argumentet root_dir.

shutil.unregister_archive_format(name)

Ta bort arkivformatet name från listan över format som stöds.

shutil.unpack_archive(filename[, extract_dir[, format[, filter]]])

Packa upp ett arkiv. filnamn är den fullständiga sökvägen till arkivet.

extract_dir är namnet på den målkatalog där arkivet ska packas upp. Om det inte anges används den aktuella arbetskatalogen.

format är arkivformatet: ett av ”zip”, ”tar”, ”gztar”, ”bztar”, ”xztar” eller ”zstdtar”. Eller något annat format som registrerats med register_unpack_format(). Om inget anges kommer unpack_archive() att använda arkivets filnamnstillägg och se om en uppackare har registrerats för det tillägget. Om ingen hittas, kommer ett ValueError att uppstå.

Argumentet filter, som endast innehåller nyckelord, skickas till den underliggande uppackningsfunktionen. För zip-filer accepteras inte filter. För tar-filer rekommenderas det att använda 'data' (standard sedan Python 3.14), såvida man inte använder funktioner som är specifika för tar och UNIX-liknande filsystem. (Se Filter för utsugning för detaljer)

Utlöser en auditing event shutil.unpack_archive med argumenten filename, extract_dir, format.

Varning

Extrahera aldrig arkiv från otillförlitliga källor utan föregående inspektion. Det är möjligt att filer skapas utanför den sökväg som anges i argumentet extract_dir, t.ex. medlemmar som har absoluta filnamn som börjar med ”/” eller filnamn med två punkter ”…”.

Sedan Python 3.14 kommer standardinställningarna för båda de inbyggda formaten (zip- och tar-filer) att förhindra de farligaste av sådana säkerhetsproblem, men kommer inte att förhindra alla oavsiktliga beteenden. Läs avsnittet Tips för ytterligare verifiering för tar-specifika detaljer.

Ändrad i version 3.7: Accepterar en path-like object för filename och extract_dir.

Ändrad i version 3.12: Lagt till argumentet filter.

shutil.register_unpack_format(name, extensions, function[, extra_args[, description]])

Registrerar ett uppackningsformat. name är namnet på formatet och extensions är en lista med tillägg som motsvarar formatet, t.ex. .zip för Zip-filer.

function är den anropbara funktion som kommer att användas för att packa upp arkiv. Den anropsbara funktionen kommer att ta emot:

• sökvägen till arkivet, som ett positionellt argument;

• den katalog som arkivet måste extraheras till, som ett positionellt argument;

• eventuellt ett filter nyckelordsargument, om det gavs till unpack_archive();

• ytterligare nyckelordsargument, specificerade av extra_args som en sekvens av (namn, värde)-tupler.

description kan anges för att beskriva formatet och kommer att returneras av funktionen get_unpack_formats().

shutil.unregister_unpack_format(name)

Avregistrera ett uppackningsformat. name är namnet på formatet.

shutil.get_unpack_formats()

Returnerar en lista över alla registrerade format för uppackning. Varje element i den returnerade sekvensen är en tupel (name, extensions, description).

Som standard tillhandahåller shutil dessa format:

• zip: ZIP-fil (uppackning av komprimerade filer fungerar endast om motsvarande modul finns tillgänglig).

• tar: okomprimerad tar-fil.

• gztar: gzip’ed tar-fil (om modulen zlib är tillgänglig).

• bztar: bzip2-behandlad tar-fil (om modulen bz2 är tillgänglig).

• xztar: xz’ed tar-fil (om modulen lzma är tillgänglig).

• zstdtar: Zstandardkomprimerad tar-fil (om modulen compression.zstd är tillgänglig).

Du kan registrera nya format eller tillhandahålla din egen uppackare för befintliga format genom att använda register_unpack_format().

Exempel på arkivering

I det här exemplet skapar vi ett gzip-komprimerat tar-filarkiv som innehåller alla filer som finns i .ssh-katalogen för användaren:

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))
>>> make_archive(archive_name, 'gztar', root_dir)
'/Users/tarek/myarchive.tar.gz'

Det resulterande arkivet innehåller:

$ tar -tzvf /Users/tarek/myarchive.tar.gz
drwx------ tarek/staff       0 2010-02-01 16:23:40 ./
-rw-r--r-- tarek/staff     609 2008-06-09 13:26:54 ./authorized_keys
-rwxr-xr-x tarek/staff      65 2008-06-09 13:26:54 ./config
-rwx------ tarek/staff     668 2008-06-09 13:26:54 ./id_dsa
-rwxr-xr-x tarek/staff     609 2008-06-09 13:26:54 ./id_dsa.pub
-rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa
-rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub
-rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts

Exempel på arkivering med base_dir

I det här exemplet, som liknar exemplet ovan, visar vi hur man använder make_archive(), men den här gången med base_dir. Vi har nu följande katalogstruktur:

$ tree tmp
tmp
└── root
    └── structure
        ├── content
            └── please_add.txt
        └── do_not_add.txt

I det slutliga arkivet ska please_add.txt ingå, men do_not_add.txt ska inte ingå. Därför använder vi följande:

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> make_archive(
...     archive_name,
...     'tar',
...     root_dir='tmp/root',
...     base_dir='structure/content',
... )
'/Users/tarek/my_archive.tar'

En lista över filerna i det resulterande arkivet ger oss:

$ python -m tarfile -l /Users/tarek/myarchive.tar
structure/content/
structure/content/please_add.txt

Fråga om storleken på utdataterminalen

shutil.get_terminal_size(fallback=(columns, lines))

Hämta storleken på terminalfönstret.

För var och en av de två dimensionerna kontrolleras miljövariabeln COLUMNS respektive LINES. Om variabeln är definierad och värdet är ett positivt heltal används den.

När COLUMNS eller LINES inte är definierade, vilket är det vanliga fallet, frågas terminalen som är ansluten till sys.__stdout__ genom att anropa os.get_terminal_size().

Om det inte går att fråga efter terminalstorleken, antingen för att systemet inte stöder en sådan fråga eller för att vi inte är anslutna till en terminal, används det värde som anges i parametern fallback. standardvärdet för fallback är (80, 24), vilket är den standardstorlek som används av många terminalemulatorer.

Det värde som returneras är en namngiven tupel av typen os.terminal_size.

Se även: The Single UNIX Specification, Version 2, Other Environment Variables.

Tillagd i version 3.3.

Ändrad i version 3.11: fallback-värdena används också om os.get_terminal_size() returnerar noll.