shutil — High-level file operations

소스 코드: Lib/shutil.py

---

shutil 모듈은 파일과 파일 모음에 대한 여러 가지 고수준 연산을 제공합니다. 특히, 파일 복사와 삭제를 지원하는 함수가 제공됩니다. 개별 파일에 대한 연산에 대해서는, os 모듈도 참조하십시오.

경고

더 고수준의 파일 복사 함수(shutil.copy(), shutil.copy2())조차도 모든 파일 메타 데이터를 복사할 수는 없습니다.

POSIX 플랫폼에서, 이는 ACL뿐만 아니라 파일 소유자와 그룹이 유실됨을 의미합니다. Mac OS에서는, 리소스 포크(resource fork)와 기타 메타 데이터가 사용되지 않습니다. 이는 리소스가 손실되고 파일 유형과 작성자 코드가 올바르지 않음을 의미합니다. 윈도우에서는, 파일 소유자, ACL 및 대체 데이터 스트림(alternate data streams)이 복사되지 않습니다.

디렉터리와 파일 연산

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

Copy the contents of the file-like object fsrc to the file-like object fdst. The integer length, if given, is the buffer size. In particular, a negative length value means to copy the data without looping over the source data in chunks; by default the data is read in chunks to avoid uncontrolled memory consumption. Note that if the current file position of the fsrc object is not 0, only the contents from the current file position to the end of the file will be copied.

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

Copy the contents (no metadata) of the file named src to a file named dst and return dst in the most efficient way possible. src and dst are path-like objects or path names given as strings.

dst는 완전한 대상 파일 이름이어야 합니다; 대상 디렉터리 경로를 허용하는 복사는 copy()를 참조하십시오. src와 dst가 같은 파일을 지정하면, SameFileError가 발생합니다.

대상 위치는 쓰기 가능해야 합니다; 그렇지 않으면, OSError 예외가 발생합니다. dst가 이미 존재하면, 교체됩니다. 문자나 블록 장치 및 파이프와 같은 특수 파일은 이 함수로 복사할 수 없습니다.

follow_symlinks가 거짓이고 src가 심볼릭 링크이면, src가 가리키는 파일을 복사하는 대신 새 심볼릭 링크가 만들어집니다.

인자 src, dst로 감사 이벤트 shutil.copyfile을 발생시킵니다.

버전 3.3에서 변경: 예전에는 OSError 대신 IOError를 발생시켰습니다. follow_symlinks 인자가 추가되었습니다. 이제 dst를 반환합니다.

버전 3.4에서 변경: Error 대신 SameFileError를 발생시킵니다. 후자는 전자의 서브 클래스라서, 이 변경은 이전 버전과 호환됩니다.

버전 3.8에서 변경: 파일을 더 효율적으로 복사하기 위해 플랫폼별 빠른 복사(fast-copy) 시스템 호출을 내부적으로 사용할 수 있습니다. 플랫폼 의존적 효율적인 복사 연산 섹션을 참조하십시오.

exception shutil.SameFileError

이 예외는 copyfile()의 소스와 대상이 같은 파일일 때 발생합니다.

Added in version 3.4.

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

Copy the permission bits from src to dst. The file contents, owner, and group are unaffected. src and dst are path-like objects or path names given as strings. If follow_symlinks is false, and both src and dst are symbolic links, copymode() will attempt to modify the mode of dst itself (rather than the file it points to). This functionality is not available on every platform; please see copystat() for more information. If copymode() cannot modify symbolic links on the local platform, and it is asked to do so, it will do nothing and return.

인자 src, dst로 감사 이벤트 shutil.copymode를 발생시킵니다.

버전 3.3에서 변경: follow_symlinks 인자가 추가되었습니다.

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

Copy the permission bits, last access time, last modification time, and flags from src to dst. On Linux, copystat() also copies the “extended attributes” where possible. The file contents, owner, and group are unaffected. src and dst are path-like objects or path names given as strings.

follow_symlinks가 거짓이고 src와 dst가 모두 심볼릭 링크를 참조하면, copystat()은 심볼릭 링크가 참조하는 파일이 아닌 심볼릭 링크 자체에 대해 작동합니다 - src 심볼릭 링크에서 정보를 읽고, dst 심볼릭 링크로 정보를 씁니다.

참고

모든 플랫폼이 심볼릭 링크를 검사하고 수정할 수 있는 기능을 제공하지는 않습니다. 파이썬 자체는 어떤 기능이 로컬에서 사용 가능한지 알려줄 수 있습니다.

• os.chmod in os.supports_follow_symlinks가 True이면, copystat()은 심볼릭 링크의 권한 비트를 수정할 수 있습니다.

• os.utime in os.supports_follow_symlinks가 True이면, copystat()은 심볼릭 링크의 마지막 액세스와 수정 시간을 수정할 수 있습니다.

• os.chflags in os.supports_follow_symlinks가 True이면, copystat()은 심볼릭 링크의 플래그를 수정할 수 있습니다. (os.chflags가 모든 플랫폼에서 사용 가능한 것은 아닙니다.)

이 기능 중 일부나 전부를 사용할 수 없는 플랫폼에서, 심볼릭 링크를 수정하라는 요청을 하면, copystat()은 가능한 모든 것들을 복사합니다. copystat()은 절대 실패를 반환하지 않습니다.

자세한 내용은 os.supports_follow_symlinks를 참조하십시오.

인자 src, dst로 감사 이벤트 shutil.copystat을 발생시킵니다.

버전 3.3에서 변경: follow_symlinks 인자와 리눅스 확장 어트리뷰트 지원을 추가했습니다.

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

Copies the file src to the file or directory dst. src and dst should be path-like objects or strings. If dst specifies a directory, the file will be copied into dst using the base filename from src. If dst specifies a file that already exists, it will be replaced. Returns the path to the newly created file.

follow_symlinks가 거짓이고, src가 심볼릭 링크이면, dst는 심볼릭 링크로 만들어집니다. follow_symlinks가 참이고 src가 심볼릭 링크이면, dst는 src가 참조하는 파일의 사본이 됩니다.

copy()는 파일 데이터와 파일의 권한 모드(os.chmod()를 참조하십시오)를 복사합니다. 파일의 생성과 수정 시간과 같은 다른 메타 데이터는 유지되지 않습니다. 원본의 모든 파일 메타 데이터를 유지하려면 대신 copy2()를 사용하십시오.

인자 src, dst로 감사 이벤트 shutil.copyfile을 발생시킵니다.

인자 src, dst로 감사 이벤트 shutil.copymode를 발생시킵니다.

버전 3.3에서 변경: follow_symlinks 인자가 추가되었습니다. 이제 새로 만든 파일의 경로를 반환합니다.

버전 3.8에서 변경: 파일을 더 효율적으로 복사하기 위해 플랫폼별 빠른 복사(fast-copy) 시스템 호출을 내부적으로 사용할 수 있습니다. 플랫폼 의존적 효율적인 복사 연산 섹션을 참조하십시오.

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

copy2()가 파일 메타 데이터 보존도 시도한다는 점을 제외하고는 copy()와 동일합니다.

When follow_symlinks is false, and src is a symbolic link, copy2() attempts to copy all metadata from the src symbolic link to the newly created dst symbolic link. However, this functionality is not available on all platforms. On platforms where some or all of this functionality is unavailable, copy2() will preserve all the metadata it can; copy2() never raises an exception because it cannot preserve file metadata.

copy2()는 copystat()을 사용하여 파일 메타 데이터를 복사합니다. 심볼릭 링크 메타 데이터 수정을 위한 플랫폼 지원에 대한 자세한 정보는 copystat()을 참조하십시오.

인자 src, dst로 감사 이벤트 shutil.copyfile을 발생시킵니다.

인자 src, dst로 감사 이벤트 shutil.copystat을 발생시킵니다.

버전 3.3에서 변경: follow_symlinks 인자를 추가하고, 확장 파일 시스템 어트리뷰트도 복사하려고 합니다 (현재 리눅스만 해당합니다). 이제 새로 만든 파일의 경로를 반환합니다.

버전 3.8에서 변경: 파일을 더 효율적으로 복사하기 위해 플랫폼별 빠른 복사(fast-copy) 시스템 호출을 내부적으로 사용할 수 있습니다. 플랫폼 의존적 효율적인 복사 연산 섹션을 참조하십시오.

shutil.ignore_patterns(*patterns)

이 팩토리 함수는 copytree()의 ignore 인자를 위한 콜러블 함수로 사용할 수 있는 함수를 만드는데, 제공된 glob 스타일 patterns 중 하나와 일치하는 파일과 디렉터리를 무시하도록 합니다. 아래 예를 참조하십시오.

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

Recursively copy an entire directory tree rooted at src to a directory named dst and return the destination directory. All intermediate directories needed to contain dst will also be created by default.

디렉터리의 권한과 시간은 copystat()으로 복사되고, 개별 파일은 copy2()를 사용하여 복사됩니다.

symlinks가 참이면, 소스 트리의 심볼릭 링크가 새 트리에서 심볼릭 링크로 표시되고 플랫폼이 허용하는 한 원래 링크의 메타 데이터가 복사됩니다; 거짓이거나 생략되면, 링크된 파일의 내용과 메타 데이터가 새 트리에 복사됩니다.

When symlinks is false, if the file pointed to by the symlink doesn’t exist, an exception will be added in the list of errors raised in an Error exception at the end of the copy process. You can set the optional ignore_dangling_symlinks flag to true if you want to silence this exception. Notice that this option has no effect on platforms that don’t support os.symlink().

ignore가 주어지면, copytree()가 방문하는 디렉터리와 os.listdir()가 반환한 이 디렉터리 내용의 리스트를 인자로 수신하는 콜러블 이어야 합니다. copytree()는 재귀적으로 호출되기 때문에, 복사되는 디렉터리마다 ignore 콜러블이 한 번 호출됩니다. 콜러블은 현재 디렉터리에 상대적인 디렉터리와 파일 이름의 시퀀스를 반환해야 합니다 (즉, 두 번째 인자에 있는 항목의 부분집합); 이 이름들은 복사 과정에서 무시됩니다. ignore_patterns()를 사용하여 glob 스타일 패턴을 기반으로 이름을 무시하는 콜러블을 만들 수 있습니다.

예외가 발생하면, 이유 리스트와 함께 Error가 발생합니다.

copy_function이 제공되면, 각 파일을 복사하는 데 사용되는 콜러블 이어야 합니다. 소스 경로와 대상 경로를 인자로 호출됩니다. 기본적으로, copy2()가 사용되지만, 같은 서명을 지원하는 (copy()와 같은) 모든 함수를 사용할 수 있습니다.

If dirs_exist_ok is false (the default) and dst already exists, a FileExistsError is raised. If dirs_exist_ok is true, the copying operation will continue if it encounters existing directories, and files within the dst tree will be overwritten by corresponding files from the src tree.

인자 src, dst로 감사 이벤트 shutil.copytree를 발생시킵니다.

버전 3.2에서 변경: Added the copy_function argument to be able to provide a custom copy function. Added the ignore_dangling_symlinks argument to silence dangling symlinks errors when symlinks is false.

버전 3.3에서 변경: symlinks가 거짓일 때 메타 데이터를 복사합니다. 이제 dst를 반환합니다.

버전 3.8에서 변경: 파일을 더 효율적으로 복사하기 위해 플랫폼별 빠른 복사(fast-copy) 시스템 호출을 내부적으로 사용할 수 있습니다. 플랫폼 의존적 효율적인 복사 연산 섹션을 참조하십시오.

버전 3.8에서 변경: Added the dirs_exist_ok parameter.

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

Delete an entire directory tree; path must point to a directory (but not a symbolic link to a directory). If ignore_errors is true, errors resulting from failed removals will be ignored; if false or omitted, such errors are handled by calling a handler specified by onexc or onerror or, if both are omitted, exceptions are propagated to the caller.

This function can support paths relative to directory descriptors.

참고

필요한 fd 기반 함수를 지원하는 플랫폼에서는 기본적으로 rmtree()의 심볼릭 링크 공격 방지 버전이 사용됩니다. 다른 플랫폼에서는, rmtree() 구현이 심볼릭 링크 공격에 취약합니다: 적절한 타이밍과 상황에 따라, 공격자는 파일 시스템에서 심볼릭 링크를 조작하여 다른 방법으로는 액세스할 수 없는 파일을 삭제할 수 있습니다. 응용 프로그램은 rmtree.avoids_symlink_attacks 함수 어트리뷰트를 사용하여 어떤 버전이 사용되는지 판별할 수 있습니다.

If onexc is provided, it must be a callable that accepts three parameters: function, path, and excinfo.

The first parameter, function, is the function which raised the exception; it depends on the platform and implementation. The second parameter, path, will be the path name passed to function. The third parameter, excinfo, is the exception that was raised. Exceptions raised by onexc will not be caught.

The deprecated onerror is similar to onexc, except that the third parameter it receives is the tuple returned from sys.exc_info().

Raises an auditing event shutil.rmtree with arguments path, dir_fd.

버전 3.3에서 변경: 플랫폼이 fd 기반 함수를 지원하면 자동으로 사용되는 심볼릭 링크 공격 방지 버전을 추가했습니다.

버전 3.8에서 변경: 윈도우에서, 정션(junction)을 제거하기 전에 더는 디렉터리 정션의 내용을 삭제하지 않습니다.

버전 3.11에서 변경: Added the dir_fd parameter.

버전 3.12에서 변경: Added the onexc parameter, deprecated onerror.

버전 3.13에서 변경: rmtree() now ignores FileNotFoundError exceptions for all but the top-level path. Exceptions other than OSError and subclasses of OSError are now always propagated to the caller.

rmtree.avoids_symlink_attacks

현재 플랫폼과 구현이 rmtree()의 심볼릭 링크 공격 방지 버전을 제공하는지를 나타냅니다. 현재 이것은 fd 기반 디렉터리 액세스 함수를 지원하는 플랫폼에서만 참입니다.

Added in version 3.3.

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

Recursively move a file or directory (src) to another location and return the destination.

If dst is an existing directory or a symlink to a directory, then src is moved inside that directory. The destination path in that directory must not already exist.

If dst already exists but is not a directory, it may be overwritten depending on os.rename() semantics.

If the destination is on the current filesystem, then os.rename() is used. Otherwise, src is copied to the destination using copy_function and then removed. In case of symlinks, a new symlink pointing to the target of src will be created as the destination and src will be removed.

If copy_function is given, it must be a callable that takes two arguments, src and the destination, and will be used to copy src to the destination if os.rename() cannot be used. If the source is a directory, copytree() is called, passing it the copy_function. The default copy_function is copy2(). Using copy() as the copy_function allows the move to succeed when it is not possible to also copy the metadata, at the expense of not copying any of the metadata.

인자 src, dst로 감사 이벤트 shutil.move를 발생시킵니다.

버전 3.3에서 변경: 외부 파일 시스템에 대한 명시적 심볼릭 링크 처리를 추가하여, GNU mv의 동작에 맞게 조정했습니다. 이제 dst를 반환합니다.

버전 3.5에서 변경: copy_function 키워드 인자를 추가했습니다.

버전 3.8에서 변경: 파일을 더 효율적으로 복사하기 위해 플랫폼별 빠른 복사(fast-copy) 시스템 호출을 내부적으로 사용할 수 있습니다. 플랫폼 의존적 효율적인 복사 연산 섹션을 참조하십시오.

버전 3.9에서 변경: src와 dst 모두에 대해 경로류 객체를 받아들입니다.

shutil.disk_usage(path)

지정된 경로(path)에 대한 디스크 사용량 통계를 total, used 및 free 어트리뷰트를 갖는 네임드 튜플로 반환합니다. 이들은 바이트 단위의 총, 사용된, 여유 공간의 양입니다. path는 파일이나 디렉터리일 수 있습니다.

참고

On Unix filesystems, path must point to a path within a mounted filesystem partition. On those platforms, CPython doesn’t attempt to retrieve disk usage information from non-mounted filesystems.

Added in version 3.3.

버전 3.8에서 변경: 윈도우에서, path는 이제 파일이나 디렉터리일 수 있습니다.

Availability: Unix, Windows.

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

주어진 path의 소유자 user 및/또는 group을 변경합니다.

user는 시스템 사용자 이름이나 uid 일 수 있습니다; group도 마찬가지입니다. 최소한 하나의 인자가 필요합니다.

하부 함수인 os.chown()도 참조하십시오.

인자 path, user, group으로 감사 이벤트 shutil.chown을 발생시킵니다.

Availability: Unix.

Added in version 3.3.

버전 3.13에서 변경: Added dir_fd and follow_symlinks parameters.

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

주어진 cmd가 호출되면 실행될 실행 파일의 경로를 반환합니다. 아무런 cmd도 호출되지 않을 것이라면, None을 반환합니다.

mode is a permission mask passed to os.access(), by default determining if the file exists and is executable.

path is a “PATH string” specifying the directories to look in, delimited by os.pathsep. When no path is specified, the PATH environment variable is read from os.environ, falling back to os.defpath if it is not set.

On Windows, the current directory is prepended to the path if mode does not include os.X_OK. When the mode does include os.X_OK, the Windows API NeedCurrentDirectoryForExePathW will be consulted to determine if the current directory should be prepended to path. To avoid consulting the current working directory for executables: set the environment variable NoDefaultCurrentDirectoryInExePath.

Also on Windows, the PATHEXT environment variable is used to resolve commands that may not already include an extension. For example, if you call shutil.which("python"), which() will search PATHEXT to know that it should look for python.exe within the path directories. For example, on Windows:

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

This is also applied when cmd is a path that contains a directory component:

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

Added in version 3.3.

버전 3.8에서 변경: 이제 bytes 형을 받아들입니다. cmd 형이 bytes이면 결과 형도 bytes입니다.

버전 3.12에서 변경: On Windows, the current directory is no longer prepended to the search path if mode includes os.X_OK and WinAPI NeedCurrentDirectoryForExePathW(cmd) is false, else the current directory is prepended even if it is already in the search path; PATHEXT is used now even when cmd includes a directory component or ends with an extension that is in PATHEXT; and filenames that have no extension can now be found.

exception shutil.Error

이 예외는 다중 파일 연산 중에 발생한 예외를 수집합니다. copytree()의 경우, 예외 인자는 3-튜플(srcname, dstname, exception)의 리스트입니다.

플랫폼 의존적 효율적인 복사 연산

파이썬 3.8부터, 파일 복사를 수반하는 모든 함수(copyfile(), copy(), copy2(), copytree() 및 move())는 파일을 더 효율적으로 복사하기 위해 플랫폼별 “빠른 복사(fast-copy)” 시스템 호출을 사용할 수 있습니다 (bpo-33671을 참조하십시오). “빠른 복사”는 복사 연산이 커널 내에서 발생하여, “outfd.write(infd.read())”와 같이 파이썬에서 사용자 공간 버퍼 사용을 피함을 의미합니다.

macOS에서는 fcopyfile이 (메타 데이터가 아닌) 파일 내용을 복사하는 데 사용됩니다.

On Linux and Solaris os.sendfile() is used.

윈도우에서는 shutil.copyfile()이 더 큰 기본 버퍼 크기(64 KiB 대신 1 MiB)를 사용하고 shutil.copyfileobj()의 memoryview() 기반 변형이 사용됩니다.

빠른 복사 연산이 실패하고 대상 파일에 아무런 데이터도 기록되지 않았으면 shutil은 내부적으로 덜 효율적인 copyfileobj() 함수를 사용하여 조용히 폴 백 됩니다.

버전 3.8에서 변경.

버전 3.14에서 변경: Solaris now uses os.sendfile().

copytree 예

An example that uses the ignore_patterns() helper:

from shutil import copytree, ignore_patterns

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

이것은 .pyc 파일과 이름이 tmp로 시작하는 파일이나 디렉터리를 제외한 모든 것을 복사합니다.

로깅 호출을 추가하기 위해 ignore 인자를 사용하는 또 다른 예:

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)

rmtree 예

This example shows how to remove a directory tree on Windows where some of the files have their read-only bit set. It uses the onexc callback to clear the readonly bit and reattempt the remove. Any subsequent failure will propagate.

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)

아카이브 연산

Added in version 3.2.

버전 3.5에서 변경: xztar 형식에 대한 지원이 추가되었습니다.

압축 및 아카이브 된 파일을 만들고 읽는 고수준 유틸리티도 제공됩니다. 이들은 zipfile과 tarfile 모듈에 의존합니다.

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

아카이브 파일(가령 zip이나 tar)을 만들고 이름을 반환합니다.

base_name is the name of the file to create, including the path, minus any format-specific extension.

format is the archive format: one of “zip” (if the zlib module is available), “tar”, “gztar” (if the zlib module is available), “bztar” (if the bz2 module is available), or “xztar” (if the lzma module is available).

root_dir은 아카이브의 루트 디렉터리가 될 디렉터리입니다, 아카이브의 모든 경로는 이것에 상대적입니다; 예를 들어, 보통 아카이브를 만들기 전에 root_dir로 chdir 합니다.

base_dir은 아카이브를 시작할 디렉터리입니다; 즉, base_dir은 아카이브에 있는 모든 파일과 디렉터리의 공통 접두사가 됩니다. base_dir은 root_dir에 상대적으로 제공되어야 합니다. base_dir과 root_dir을 함께 사용하는 방법은 base_dir을 사용한 아카이브 예를 참조하십시오.

root_dir과 base_dir은 모두 현재 디렉터리가 기본값입니다.

dry_run이 참이면, 아카이브가 만들어지지 않지만, 실행될 연산이 logger에 로그 됩니다.

tar 아카이브를 만들 때 owner와 *group이 사용됩니다. 기본적으로, 현재 소유자와 그룹을 사용합니다.

logger는 PEP 282와 호환되는 객체여야 합니다, 일반적으로 logging.Logger의 인스턴스.

verbose 인자는 사용되지 않으며 폐지되었습니다.

인자 base_name, format, root_dir, base_dir로 감사 이벤트 shutil.make_archive를 발생시킵니다.

참고

This function is not thread-safe when custom archivers registered with register_archive_format() do not support the root_dir argument. In this case it temporarily changes the current working directory of the process to root_dir to perform archiving.

버전 3.8에서 변경: format="tar"로 만들어진 아카이브에 기존 GNU 형식 대신 최신 pax (POSIX.1-2001) 형식이 사용됩니다.

버전 3.10.6에서 변경: This function is now made thread-safe during creation of standard .zip and tar archives.

shutil.get_archive_formats()

아카이브에 지원되는 형식의 리스트를 반환합니다. 반환된 시퀀스의 각 요소는 튜플 (name, description)입니다.

기본적으로 shutil은 다음 형식을 제공합니다:

• zip: ZIP 파일 (zlib 모듈을 사용할 수 있으면).

• tar: 압축되지 않은 tar 파일. 새 아카이브에 POSIX.1-2001 pax 형식을 사용합니다.

• gztar: gzip 된 tar 파일 (zlib 모듈을 사용할 수 있으면).

• bztar: bzip2 된 tar 파일 (bz2 모듈을 사용할 수 있으면).

• xztar: xz 된 tar 파일 (lzma 모듈을 사용할 수 있으면).

register_archive_format()을 사용하여, 새 형식을 등록하거나 기존 형식에 대해 여러분 자신의 아카이버를 제공할 수 있습니다.

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

name 형식을 위한 아카이버를 등록합니다.

function은 아카이브를 만드는 데 사용되는 콜러블입니다. 콜러블은 만들 파일의 base_name과 그 뒤에 아카이브를 시작할 base_dir(기본값은 os.curdir)를 받습니다. 추가 인자는 키워드 인자로 전달됩니다: owner, group, dry_run 및 logger (make_archive()로 전달됩니다).

If function has the custom attribute function.supports_root_dir set to True, the root_dir argument is passed as a keyword argument. Otherwise the current working directory of the process is temporarily changed to root_dir before calling function. In this case make_archive() is not thread-safe.

주어지면, extra_args는 아카이버 콜러블이 사용될 때 추가 키워드 인자로 사용되는 (name, value) 쌍의 시퀀스입니다.

description은 아카이버 목록을 반환하는 get_archive_formats()에서 사용됩니다. 기본값은 빈 문자열입니다.

버전 3.12에서 변경: Added support for functions supporting the root_dir argument.

shutil.unregister_archive_format(name)

지원되는 형식 리스트에서 name 아카이브 형식을 제거합니다.

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

아카이브를 풉니다. filename은 아카이브의 전체 경로입니다.

extract_dir은 아카이브가 풀리는 대상 디렉터리의 이름입니다. 제공되지 않으면, 현재 작업 디렉터리가 사용됩니다.

format은 아카이브 형식입니다: “zip”, “tar”, “gztar”, “bztar” 또는 “xztar” 중 하나. 또는 register_unpack_format()으로 등록된 다른 형식. 제공되지 않으면, unpack_archive()는 아카이브 파일 이름 확장자를 사용하여 그 확장자에 대한 아카이브 해제기가 등록되었는지 확인합니다. 아무것도 발견되지 않으면, ValueError가 발생합니다.

The keyword-only filter argument is passed to the underlying unpacking function. For zip files, filter is not accepted. For tar files, it is recommended to use 'data' (default since Python 3.14), unless using features specific to tar and UNIX-like filesystems. (See Extraction filters for details.)

인자 filename, extract_dir, format으로 감사 이벤트 shutil.unpack_archive를 발생시킵니다.

경고

Never extract archives from untrusted sources without prior inspection. It is possible that files are created outside of the path specified in the extract_dir argument, e.g. members that have absolute filenames starting with “/” or filenames with two dots “..”.

Since Python 3.14, the defaults for both built-in formats (zip and tar files) will prevent the most dangerous of such security issues, but will not prevent all unintended behavior. Read the Hints for further verification section for tar-specific details.

버전 3.7에서 변경: filename과 extract_dir에 대해 경로류 객체를 받아들입니다.

버전 3.12에서 변경: Added the filter argument.

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

아카이브 해제기를 등록합니다. name은 형식의 이름이고 extensions는 형식에 해당하는 확장자의 리스트입니다, 가령 Zip 파일의 경우 .zip.

function is the callable that will be used to unpack archives. The callable will receive:

• the path of the archive, as a positional argument;

• the directory the archive must be extracted to, as a positional argument;

• possibly a filter keyword argument, if it was given to unpack_archive();

• additional keyword arguments, specified by extra_args as a sequence of (name, value) tuples.

description은 형식을 설명하기 위해 제공될 수 있으며, get_unpack_formats() 함수에 의해 반환됩니다.

shutil.unregister_unpack_format(name)

아카이브 해제 형식을 등록 취소합니다. name은 형식의 이름입니다.

shutil.get_unpack_formats()

아카이브 해제를 위해 등록된 모든 형식의 리스트를 반환합니다. 반환된 시퀀스의 각 요소는 튜플 (name, extensions, description)입니다.

기본적으로 shutil은 다음 형식을 제공합니다:

• zip: ZIP 파일 (압축된 파일의 해제는 해당 모듈을 사용할 수 있을 때만 작동합니다).

• tar: 압축되지 않은 tar 파일.

• gztar: gzip 된 tar 파일 (zlib 모듈을 사용할 수 있으면).

• bztar: bzip2 된 tar 파일 (bz2 모듈을 사용할 수 있으면).

• xztar: xz 된 tar 파일 (lzma 모듈을 사용할 수 있으면).

register_unpack_format()을 사용하여, 새 형식을 등록하거나 기존 형식에 대한 여러분 자신의 아카이브 해제기를 제공할 수 있습니다.

아카이브 예

이 예에서는, 사용자의 .ssh 디렉터리에 있는 모든 파일을 포함하는 gzip 된 tar 파일 아카이브를 만듭니다:

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

결과 아카이브에는 다음이 포함됩니다:

$ 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

base_dir을 사용한 아카이브 예

이 예에서는, 위의 예와 유사하게, make_archive()를 사용하는 방법을 보여 주지만, 이번에는 base_dir을 사용합니다. 이제 다음 디렉터리 구조가 있습니다:

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

최종 아카이브에는, please_add.txt가 포함되어야 하지만, do_not_add.txt는 포함되지 않아야 합니다. 따라서 다음을 사용합니다:

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

결과 아카이브에 파일을 나열하면 다음과 같습니다:

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

출력 터미널의 크기 조회하기

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

터미널 창의 크기를 가져옵니다.

두 차원 각각에 대해, 환경 변수 COLUMNS와 LINES가 각각 확인됩니다. 변수가 정의되고 값이 양의 정수이면 사용됩니다.

COLUMNS나 LINES가 정의되지 않으면 (이것이 일반적입니다), os.get_terminal_size()를 호출하여 sys.__stdout__에 연결된 터미널을 조회합니다.

시스템이 조회를 지원하지 않거나, 터미널에 연결되어 있지 않기 때문에 터미널 크기를 성공적으로 조회할 수 없으면, fallback 매개 변수에 제공된 값이 사용됩니다. fallback의 기본값은 많은 터미널 에뮬레이터에서 사용하는 기본 크기인 (80, 24)입니다.

반환된 값은 os.terminal_size 형의 네임드 튜플입니다.

참조: The Single UNIX Specification, Version 2, Other Environment Variables.

Added in version 3.3.

버전 3.11에서 변경: The fallback values are also used if os.get_terminal_size() returns zeroes.