cloudpathlib.CloudPath¶
Base class for cloud storage file URIs, in the style of the Python standard library's
pathlib module. Instances represent a path
in cloud storage with filesystem path semantics, and convenient methods allow for basic
operations like joining, reading, writing, iterating over contents, etc. CloudPath almost
entirely mimics the pathlib.Path
interface, so most familiar properties and methods should be available and behave in the
expected way.
Analogous to the way pathlib.Path works, instantiating CloudPath will instead create an
instance of an appropriate subclass that implements a particular cloud storage service, such as
S3Path. This dispatching behavior is based on the URI scheme part of a cloud
storage URI (e.g., "s3://").
Attributes¶
anchor: str
property
readonly
¶
The concatenation of the drive and root, or ''. (Docstring copied from pathlib.Path)
drive: str
property
readonly
¶
The drive prefix (letter or UNC path), if any. (Docstring copied from pathlib.Path)
fspath: str
property
readonly
¶
name
property
readonly
¶
The final path component, if any. (Docstring copied from pathlib.Path)
parent
property
readonly
¶
The logical parent of the path. (Docstring copied from pathlib.Path)
parents
property
readonly
¶
A sequence of this path's logical parents. (Docstring copied from pathlib.Path)
parts
property
readonly
¶
An object providing sequence-like access to the components in the filesystem path. (Docstring copied from pathlib.Path)
stat
property
readonly
¶
Return the result of the stat() system call on this path, like os.stat() does. (Docstring copied from pathlib.Path)
stem
property
readonly
¶
The final path component, minus its last suffix. (Docstring copied from pathlib.Path)
suffix
property
readonly
¶
The final component's last suffix, if any.
This includes the leading period. For example: '.txt' (Docstring copied from pathlib.Path)
suffixes
property
readonly
¶
A list of the final component's suffixes, if any.
These include the leading periods. For example: ['.tar', '.gz'] (Docstring copied from pathlib.Path)
Methods¶
__init__(self, cloud_path: Union[str, CloudPath], client: Optional[Client] = None)
special
¶
Source code in cloudpathlib/cloudpath.py
def __init__(self, cloud_path: Union[str, "CloudPath"], client: Optional["Client"] = None):
self.is_valid_cloudpath(cloud_path, raise_on_error=True)
# versions of the raw string that provide useful methods
self._str = str(cloud_path)
self._url = urlparse(self._str)
self._path = PurePosixPath(f"/{self._no_prefix}")
# setup client
if client is None:
if isinstance(cloud_path, CloudPath):
client = cloud_path.client
else:
client = self._cloud_meta.client_class.get_default_client()
if not isinstance(client, self._cloud_meta.client_class):
raise ClientMismatchError(
f"Client of type [{client.__class__}] is not valid for cloud path of type "
f"[{self.__class__}]; must be instance of [{self._cloud_meta.client_class}], or "
f"None to use default client for this cloud path class."
)
self.client: Client = client
# track if local has been written to, if so it may need to be uploaded
self._dirty = False
# handle if local file gets opened
self._handle = None
as_uri(self) -> str
¶
Return the path as a 'file' URI. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def as_uri(self) -> str:
return str(self)
download_to(self, destination: Union[str, os.PathLike])
¶
Source code in cloudpathlib/cloudpath.py
def download_to(self, destination: Union[str, os.PathLike]):
destination = Path(destination)
if self.is_file():
if destination.is_dir():
destination = destination / self.name
self.client._download_file(self, destination)
else:
destination.mkdir(exist_ok=True)
for f in self.iterdir():
rel = str(self)
if not rel.endswith("/"):
rel = rel + "/"
rel_dest = str(f)[len(rel) :]
f.download_to(destination / rel_dest)
exists(self) -> bool
¶
Whether this path exists. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def exists(self) -> bool:
return self.client._exists(self)
glob(self, pattern: str) -> Iterable[CloudPath]
¶
Iterate over this subtree and yield all existing files (of any kind, including directories) matching the given relative pattern. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def glob(self, pattern: str) -> Iterable["CloudPath"]:
# strip cloud prefix from pattern if it is included
if pattern.startswith(self.cloud_prefix):
pattern = pattern[len(self.cloud_prefix) :]
# strip "drive" from pattern if it is included
if pattern.startswith(self.drive + "/"):
pattern = pattern[len(self.drive + "/") :]
# identify if pattern is recursive or not
recursive = False
if pattern.startswith("**/"):
pattern = pattern.split("/", 1)[-1]
recursive = True
for f in self.client._list_dir(self, recursive=recursive):
if fnmatch.fnmatch(f._no_prefix_no_drive, pattern):
yield f
is_dir(self) -> bool
¶
Whether this path is a directory. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
@abc.abstractmethod
def is_dir(self) -> bool:
"""Should be implemented without requiring a dir is downloaded"""
pass
is_file(self) -> bool
¶
Whether this path is a regular file (also True for symlinks pointing to regular files). (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
@abc.abstractmethod
def is_file(self) -> bool:
"""Should be implemented without requiring that the file is downloaded"""
pass
is_valid_cloudpath(path: Union[str, CloudPath], raise_on_error = False) -> bool
classmethod
¶
Source code in cloudpathlib/cloudpath.py
@classmethod
def is_valid_cloudpath(cls, path: Union[str, "CloudPath"], raise_on_error=False) -> bool:
valid = str(path).lower().startswith(cls.cloud_prefix.lower())
if raise_on_error and not valid:
raise InvalidPrefixError(
f"'{path}' is not a valid path since it does not start with '{cls.cloud_prefix}'"
)
return valid
iterdir(self) -> Iterable[CloudPath]
¶
Iterate over the files in this directory. Does not yield any result for the special paths '.' and '..'. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def iterdir(self) -> Iterable["CloudPath"]:
for f in self.client._list_dir(self, recursive=False):
yield f
joinpath(self, *args)
¶
Combine this path with one or several arguments, and return a new path representing either a subpath (if all arguments are relative paths) or a totally different path (if one of the arguments is anchored). (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def joinpath(self, *args):
return self._dispatch_to_path("joinpath", *args)
match(self, path_pattern)
¶
Return True if this path matches the given pattern. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def match(self, path_pattern):
# strip scheme from start of pattern before testing
if path_pattern.startswith(self.anchor + self.drive + "/"):
path_pattern = path_pattern[len(self.anchor + self.drive + "/") :]
return self._dispatch_to_path("match", path_pattern)
mkdir(self, parents: bool = False, exist_ok: bool = False)
¶
Create a new directory at this given path. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
@abc.abstractmethod
def mkdir(self, parents: bool = False, exist_ok: bool = False):
"""Should be implemented using the client API without requiring a dir is downloaded"""
pass
open(self, mode = 'r', buffering = -1, encoding = None, errors = None, newline = None, force_overwrite_from_cloud = False, force_overwrite_to_cloud = False) -> IO
¶
Open the file pointed by this path and return a file object, as the built-in open() function does. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def open(
self,
mode="r",
buffering=-1,
encoding=None,
errors=None,
newline=None,
force_overwrite_from_cloud=False, # extra kwarg not in pathlib
force_overwrite_to_cloud=False, # extra kwarg not in pathlib
) -> IO:
# if trying to call open on a directory that exists
if self.exists() and not self.is_file():
raise CloudPathIsADirectoryError(
f"Cannot open directory, only files. Tried to open ({self})"
)
if mode == "x" and self.exists():
raise CloudPathFileExistsError(f"Cannot open existing file ({self}) for creation.")
# TODO: consider streaming from client rather than DLing entire file to cache
self._refresh_cache(force_overwrite_from_cloud=force_overwrite_from_cloud)
# create any directories that may be needed if the file is new
if not self._local.exists():
self._local.parent.mkdir(parents=True, exist_ok=True)
original_mtime = 0
else:
original_mtime = self._local.stat().st_mtime
buffer = self._local.open(
mode=mode,
buffering=buffering,
encoding=encoding,
errors=errors,
newline=newline,
)
# write modes need special on closing the buffer
if any(m in mode for m in ("w", "+", "x", "a")):
# dirty, handle, patch close
original_close = buffer.close
# since we are pretending this is a cloud file, upload it to the cloud
# when the buffer is closed
def _patched_close(*args, **kwargs):
original_close(*args, **kwargs)
# original mtime should match what was in the cloud; because of system clocks or rounding
# by the cloud provider, the new version in our cache is "older" than the original version;
# explicitly set the new modified time to be after the original modified time.
if self._local.stat().st_mtime < original_mtime:
new_mtime = original_mtime + 1
os.utime(self._local, times=(new_mtime, new_mtime))
self._upload_local_to_cloud(force_overwrite_to_cloud=force_overwrite_to_cloud)
buffer.close = _patched_close
# keep reference in case we need to close when __del__ is called on this object
self._handle = buffer
# opened for write, so mark dirty
self._dirty = True
return buffer
read_bytes(self)
¶
Open the file in bytes mode, read it, and close the file. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def read_bytes(self):
return self._dispatch_to_local_cache_path("read_bytes")
read_text(self)
¶
Open the file in text mode, read it, and close the file. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def read_text(self):
return self._dispatch_to_local_cache_path("read_text")
rename(self, target: CloudPath) -> CloudPath
¶
Rename this path to the target path.
The target path may be absolute or relative. Relative paths are interpreted relative to the current working directory, not the directory of the Path object.
Returns the new Path instance pointing to the target path. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def rename(self, target: "CloudPath") -> "CloudPath":
# for cloud services replace == rename since we don't just rename,
# we actually move files
return self.replace(target)
replace(self, target: CloudPath) -> CloudPath
¶
Rename this path to the target path, overwriting if that path exists.
The target path may be absolute or relative. Relative paths are interpreted relative to the current working directory, not the directory of the Path object.
Returns the new Path instance pointing to the target path. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def replace(self, target: "CloudPath") -> "CloudPath":
if type(self) != type(target):
raise TypeError(
f"The target based to rename must be an instantiated class of type: {type(self)}"
)
if target.exists():
target.unlink()
self.client._move_file(self, target)
return target
rglob(self, pattern: str) -> Iterable[CloudPath]
¶
Recursively yield all existing files (of any kind, including directories) matching the given relative pattern, anywhere in this subtree. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def rglob(self, pattern: str) -> Iterable["CloudPath"]:
return self.glob("**/" + pattern)
rmdir(self)
¶
Remove this directory. The directory must be empty. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def rmdir(self):
if self.is_file():
raise CloudPathNotADirectoryError(
f"Path {self} is a file; call unlink instead of rmdir."
)
try:
next(self.iterdir())
raise DirectoryNotEmptyError(
f"Directory not empty: '{self}'. Use rmtree to delete recursively."
)
except StopIteration:
pass
self.client._remove(self)
rmtree(self)
¶
Delete an entire directory tree.
Source code in cloudpathlib/cloudpath.py
def rmtree(self):
"""Delete an entire directory tree."""
if self.is_file():
raise CloudPathNotADirectoryError(
f"Path {self} is a file; call unlink instead of rmtree."
)
self.client._remove(self)
samefile(self, other_path: CloudPath) -> bool
¶
Return whether other_path is the same or not as this file (as returned by os.path.samefile()). (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def samefile(self, other_path: "CloudPath") -> bool:
# all cloud paths are absolute and the paths are used for hash
return self == other_path
touch(self)
¶
Create this file with the given access mode, if it doesn't exist. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
@abc.abstractmethod
def touch(self):
"""Should be implemented using the client API to create and update modified time"""
pass
unlink(self)
¶
Remove this file or link. If the path is a directory, use rmdir() instead. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def unlink(self):
if self.is_dir():
raise CloudPathIsADirectoryError(
f"Path {self} is a directory; call rmdir instead of unlink."
)
self.client._remove(self)
with_name(self, name)
¶
Return a new path with the file name changed. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def with_name(self, name):
return self._dispatch_to_path("with_name", name)
with_suffix(self, suffix)
¶
Return a new path with the file suffix changed. If the path has no suffix, add given suffix. If the given suffix is an empty string, remove the suffix from the path. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def with_suffix(self, suffix):
return self._dispatch_to_path("with_suffix", suffix)
write_bytes(self, data: bytes)
¶
Open the file in bytes mode, write to it, and close the file. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def write_bytes(self, data: bytes):
"""Open the file in bytes mode, write to it, and close the file.
NOTE: vendored from pathlib since we override open
https://github.com/python/cpython/blob/3.8/Lib/pathlib.py#L1235-L1242
"""
# type-check for the buffer interface before truncating the file
view = memoryview(data)
with self.open(mode="wb") as f:
return f.write(view)
write_text(self, data: str, encoding = None, errors = None)
¶
Open the file in text mode, write to it, and close the file. (Docstring copied from pathlib.Path)
Source code in cloudpathlib/cloudpath.py
def write_text(self, data: str, encoding=None, errors=None):
"""Open the file in text mode, write to it, and close the file.
NOTE: vendored from pathlib since we override open
https://github.com/python/cpython/blob/3.8/Lib/pathlib.py#L1244-L1252
"""
if not isinstance(data, str):
raise TypeError("data must be str, not %s" % data.__class__.__name__)
with self.open(mode="w", encoding=encoding, errors=errors) as f:
return f.write(data)