pip._internal.utils.unpacking Namespace Reference

Functions
int	current_umask ()
List[str]	split_leading_dir (str path)
bool	has_leading_dir (Iterable[str] paths)
bool	is_within_directory (str directory, str target)
None	set_extracted_file_to_default_mode_plus_executable (str path)
bool	zip_item_is_executable (ZipInfo info)
None	unzip_file (str filename, str location, bool flatten=True)
None	untar_file (str filename, str location)
None	unpack_file (str filename, str location, Optional[str] content_type=None)

Variables
	logger = logging.getLogger(__name__)
	SUPPORTED_EXTENSIONS = ZIP_EXTENSIONS + TAR_EXTENSIONS

Detailed Description

Utilities related archives.

Function Documentation

current_umask()

int current_umask

(

)

Get the current umask which involves having to set it temporarily.

Definition at line 43 of file unpacking.py.

def current_umask() -> int:
    """Get the current umask which involves having to set it temporarily."""
    mask = os.umask(0)
    os.umask(mask)
    return mask
 
 

References i.

Referenced by pip._internal.utils.unpacking.set_extracted_file_to_default_mode_plus_executable().

Here is the caller graph for this function:

has_leading_dir()

bool has_leading_dir

(

Iterable[str]

paths

)

Returns true if all the paths have the same leading path name
(i.e., everything is in one subdirectory in an archive)

Definition at line 62 of file unpacking.py.

def has_leading_dir(paths: Iterable[str]) -> bool:
    """Returns true if all the paths have the same leading path name
    (i.e., everything is in one subdirectory in an archive)"""
    common_prefix = None
    for path in paths:
        prefix, rest = split_leading_dir(path)
        if not prefix:
            return False
        elif common_prefix is None:
            common_prefix = prefix
        elif prefix != common_prefix:
            return False
    return True
 
 

References pip._internal.utils.unpacking.split_leading_dir().

Referenced by pip._internal.utils.unpacking.untar_file(), and pip._internal.utils.unpacking.unzip_file().

Here is the call graph for this function:

Here is the caller graph for this function:

is_within_directory()

bool is_within_directory	(	str	directory,
		str	target
	)

Return true if the absolute path of target is within the directory

Definition at line 77 of file unpacking.py.

def is_within_directory(directory: str, target: str) -> bool:
    """
    Return true if the absolute path of target is within the directory
    """
    abs_directory = os.path.abspath(directory)
    abs_target = os.path.abspath(target)
 
    prefix = os.path.commonprefix([abs_directory, abs_target])
    return prefix == abs_directory
 
 

References i.

set_extracted_file_to_default_mode_plus_executable()

None set_extracted_file_to_default_mode_plus_executable

(

str

path

)

Make file present at path have execute for user/group/world
(chmod +x) is no-op on windows per python docs

Definition at line 88 of file unpacking.py.

def set_extracted_file_to_default_mode_plus_executable(path: str) -> None:
    """
    Make file present at path have execute for user/group/world
    (chmod +x) is no-op on windows per python docs
    """
    os.chmod(path, (0o777 & ~current_umask() | 0o111))
 
 

References pip._internal.utils.unpacking.current_umask(), and i.

Here is the call graph for this function:

split_leading_dir()

List[str] split_leading_dir

(

str

path

)

Definition at line 50 of file unpacking.py.

def split_leading_dir(path: str) -> List[str]:
    path = path.lstrip("/").lstrip("\\")
    if "/" in path and (
        ("\\" in path and path.find("/") < path.find("\\")) or "\\" not in path
    ):
        return path.split("/", 1)
    elif "\\" in path:
        return path.split("\\", 1)
    else:
        return [path, ""]
 
 

References i.

Referenced by pip._internal.utils.unpacking.has_leading_dir(), pip._internal.utils.unpacking.untar_file(), and pip._internal.utils.unpacking.unzip_file().

Here is the caller graph for this function:

unpack_file()

None unpack_file	(	str	filename,
		str	location,
		Optional[str]	content_type = None
	)

Definition at line 229 of file unpacking.py.

) -> None:
    filename = os.path.realpath(filename)
    if (
        content_type == "application/zip"
        or filename.lower().endswith(ZIP_EXTENSIONS)
        or zipfile.is_zipfile(filename)
    ):
        unzip_file(filename, location, flatten=not filename.endswith(".whl"))
    elif (
        content_type == "application/x-gzip"
        or tarfile.is_tarfile(filename)
        or filename.lower().endswith(TAR_EXTENSIONS + BZ2_EXTENSIONS + XZ_EXTENSIONS)
    ):
        untar_file(filename, location)
    else:
        # FIXME: handle?
        # FIXME: magic signatures?
        logger.critical(
            "Cannot unpack file %s (downloaded from %s, content-type: %s); "
            "cannot detect archive format",
            filename,
            location,
            content_type,
        )
        raise InstallationError(f"Cannot determine archive format of {location}")

References i, pip._internal.utils.unpacking.untar_file(), and pip._internal.utils.unpacking.unzip_file().

Here is the call graph for this function:

untar_file()

None untar_file	(	str	filename,
		str	location
	)

Untar the file (with path `filename`) to the destination `location`.
All files are written based on system defaults and umask (i.e. permissions
are not preserved), except that regular file members with any execute
permissions (user, group, or world) have "chmod +x" applied after being
written.  Note that for windows, any execute changes using os.chmod are
no-ops per the python docs.

Definition at line 149 of file unpacking.py.

def untar_file(filename: str, location: str) -> None:
    """
    Untar the file (with path `filename`) to the destination `location`.
    All files are written based on system defaults and umask (i.e. permissions
    are not preserved), except that regular file members with any execute
    permissions (user, group, or world) have "chmod +x" applied after being
    written.  Note that for windows, any execute changes using os.chmod are
    no-ops per the python docs.
    """
    ensure_dir(location)
    if filename.lower().endswith(".gz") or filename.lower().endswith(".tgz"):
        mode = "r:gz"
    elif filename.lower().endswith(BZ2_EXTENSIONS):
        mode = "r:bz2"
    elif filename.lower().endswith(XZ_EXTENSIONS):
        mode = "r:xz"
    elif filename.lower().endswith(".tar"):
        mode = "r"
    else:
        logger.warning(
            "Cannot determine compression type for file %s",
            filename,
        )
        mode = "r:*"
    tar = tarfile.open(filename, mode, encoding="utf-8")
    try:
        leading = has_leading_dir([member.name for member in tar.getmembers()])
        for member in tar.getmembers():
            fn = member.name
            if leading:
                fn = split_leading_dir(fn)[1]
            path = os.path.join(location, fn)
            if not is_within_directory(location, path):
                message = (
                    "The tar file ({}) has a file ({}) trying to install "
                    "outside target directory ({})"
                )
                raise InstallationError(message.format(filename, path, location))
            if member.isdir():
                ensure_dir(path)
            elif member.issym():
                try:
                    tar._extract_member(member, path)
                except Exception as exc:
                    # Some corrupt tar files seem to produce this
                    # (specifically bad symlinks)
                    logger.warning(
                        "In the tar file %s the member %s is invalid: %s",
                        filename,
                        member.name,
                        exc,
                    )
                    continue
            else:
                try:
                    fp = tar.extractfile(member)
                except (KeyError, AttributeError) as exc:
                    # Some corrupt tar files seem to produce this
                    # (specifically bad symlinks)
                    logger.warning(
                        "In the tar file %s the member %s is invalid: %s",
                        filename,
                        member.name,
                        exc,
                    )
                    continue
                ensure_dir(os.path.dirname(path))
                assert fp is not None
                with open(path, "wb") as destfp:
                    shutil.copyfileobj(fp, destfp)
                fp.close()
                # Update the timestamp (useful for cython compiled files)
                tar.utime(member, path)
                # member have any execute permissions for user/group/world?
                if member.mode & 0o111:
                    set_extracted_file_to_default_mode_plus_executable(path)
    finally:
        tar.close()
 
 

References pip._internal.utils.unpacking.has_leading_dir(), i, and pip._internal.utils.unpacking.split_leading_dir().

Referenced by pip._internal.utils.unpacking.unpack_file().

Here is the call graph for this function:

Here is the caller graph for this function:

unzip_file()

None unzip_file	(	str	filename,
		str	location,
		bool	flatten = True
	)

Unzip the file (with path `filename`) to the destination `location`.  All
files are written based on system defaults and umask (i.e. permissions are
not preserved), except that regular file members with any execute
permissions (user, group, or world) have "chmod +x" applied after being
written. Note that for windows, any execute changes using os.chmod are
no-ops per the python docs.

Definition at line 103 of file unpacking.py.

def unzip_file(filename: str, location: str, flatten: bool = True) -> None:
    """
    Unzip the file (with path `filename`) to the destination `location`.  All
    files are written based on system defaults and umask (i.e. permissions are
    not preserved), except that regular file members with any execute
    permissions (user, group, or world) have "chmod +x" applied after being
    written. Note that for windows, any execute changes using os.chmod are
    no-ops per the python docs.
    """
    ensure_dir(location)
    zipfp = open(filename, "rb")
    try:
        zip = zipfile.ZipFile(zipfp, allowZip64=True)
        leading = has_leading_dir(zip.namelist()) and flatten
        for info in zip.infolist():
            name = info.filename
            fn = name
            if leading:
                fn = split_leading_dir(name)[1]
            fn = os.path.join(location, fn)
            dir = os.path.dirname(fn)
            if not is_within_directory(location, fn):
                message = (
                    "The zip file ({}) has a file ({}) trying to install "
                    "outside target directory ({})"
                )
                raise InstallationError(message.format(filename, fn, location))
            if fn.endswith("/") or fn.endswith("\\"):
                # A directory
                ensure_dir(fn)
            else:
                ensure_dir(dir)
                # Don't use read() to avoid allocating an arbitrarily large
                # chunk of memory for the file's content
                fp = zip.open(name)
                try:
                    with open(fn, "wb") as destfp:
                        shutil.copyfileobj(fp, destfp)
                finally:
                    fp.close()
                    if zip_item_is_executable(info):
                        set_extracted_file_to_default_mode_plus_executable(fn)
    finally:
        zipfp.close()
 
 

References pip._internal.utils.unpacking.has_leading_dir(), i, and pip._internal.utils.unpacking.split_leading_dir().

Referenced by pip._internal.utils.unpacking.unpack_file().

Here is the call graph for this function:

Here is the caller graph for this function:

zip_item_is_executable()

bool zip_item_is_executable

(

ZipInfo

info

)

Definition at line 96 of file unpacking.py.

def zip_item_is_executable(info: ZipInfo) -> bool:
    mode = info.external_attr >> 16
    # if mode and regular file and any execute permissions for
    # user/group/world?
    return bool(mode and stat.S_ISREG(mode) and mode & 0o111)
 
 

References i.

Variable Documentation

logger

logger = logging.getLogger(__name__)

Definition at line 22 of file unpacking.py.

SUPPORTED_EXTENSIONS

SUPPORTED_EXTENSIONS = ZIP_EXTENSIONS + TAR_EXTENSIONS

Definition at line 25 of file unpacking.py.