Skip to content

cloudpathlib.local

This module implements "Local" classes that mimic their associated cloudpathlib non-local counterparts but use the local filesystem in place of cloud storage. They can be used as drop-in replacements, with the intent that you can use them as mock or monkepatch substitutes in your tests. See "Testing code that uses cloudpathlib" for usage examples.

Attributes

local_azure_blob_implementation = CloudImplementation() module-attribute

Replacement for "azure" CloudImplementation meta object in cloudpathlib.implementation_registry

local_gs_implementation = CloudImplementation() module-attribute

Replacement for "gs" CloudImplementation meta object in cloudpathlib.implementation_registry

local_s3_implementation = CloudImplementation() module-attribute

Replacement for "s3" CloudImplementation meta object in cloudpathlib.implementation_registry

Classes

LocalAzureBlobClient

Bases: LocalClient

Replacement for AzureBlobClient that uses the local file system. Intended as a monkeypatch substitute when writing tests.

Source code in cloudpathlib/local/implementations/azure.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
class LocalAzureBlobClient(LocalClient):
    """Replacement for AzureBlobClient that uses the local file system. Intended as a monkeypatch
    substitute when writing tests.
    """

    _cloud_meta = local_azure_blob_implementation

    def __init__(self, *args, **kwargs):
        cred_opts = [
            kwargs.get("blob_service_client", None),
            kwargs.get("connection_string", None),
            kwargs.get("account_url", None),
            os.getenv("AZURE_STORAGE_CONNECTION_STRING", None),
        ]
        super().__init__(*args, **kwargs)

        if all(opt is None for opt in cred_opts):
            raise MissingCredentialsError(
                "AzureBlobClient does not support anonymous instantiation. "
                "Credentials are required; see docs for options."
            )

Attributes

content_type_method = content_type_method instance-attribute
file_cache_mode = file_cache_mode instance-attribute
local_storage_dir: Path property

The local directory where files are stored for this client. This storage directory is the one that simulates the cloud. If no storage directory was provided on instantiating the client, the default storage directory for this client class is used.

Methods:

CloudPath(cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath
Source code in cloudpathlib/client.py 
111
112
def CloudPath(self, cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath:
    return self._cloud_meta.path_class(cloud_path, *parts, client=self)  # type: ignore
__init__(*args, **kwargs)
Source code in cloudpathlib/local/implementations/azure.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def __init__(self, *args, **kwargs):
    cred_opts = [
        kwargs.get("blob_service_client", None),
        kwargs.get("connection_string", None),
        kwargs.get("account_url", None),
        os.getenv("AZURE_STORAGE_CONNECTION_STRING", None),
    ]
    super().__init__(*args, **kwargs)

    if all(opt is None for opt in cred_opts):
        raise MissingCredentialsError(
            "AzureBlobClient does not support anonymous instantiation. "
            "Credentials are required; see docs for options."
        )
clear_cache()

Clears the contents of the cache folder. Does not remove folder so it can keep being written to.

Source code in cloudpathlib/client.py 
114
115
116
117
118
119
120
121
122
123
def clear_cache(self):
    """Clears the contents of the cache folder.
    Does not remove folder so it can keep being written to.
    """
    if self._local_cache_dir.exists():
        for p in self._local_cache_dir.iterdir():
            if p.is_file():
                p.unlink()
            else:
                shutil.rmtree(p)
get_default_client() -> Client[BoundedCloudPath] classmethod

Get the default client, which the one that is used when instantiating a cloud path instance for this cloud without a client specified.

Source code in cloudpathlib/client.py 
 97
 98
 99
100
101
102
103
104
@classmethod
def get_default_client(cls) -> "Client[BoundedCloudPath]":
    """Get the default client, which the one that is used when instantiating a cloud path
    instance for this cloud without a client specified.
    """
    if cls._default_client is None:
        cls._default_client = cls()
    return cls._default_client
get_default_storage_dir() -> Path classmethod

Return the default storage directory for this client class. This is used if a client is instantiated without a storage directory being explicitly provided. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
46
47
48
49
50
51
52
53
54
55
@classmethod
def get_default_storage_dir(cls) -> Path:
    """Return the default storage directory for this client class. This is used if a client
    is instantiated without a storage directory being explicitly provided. In this usage,
    "storage" refers to the local storage that simulates the cloud.
    """
    if cls._default_storage_temp_dir is None:
        cls._default_storage_temp_dir = TemporaryDirectory()
        _temp_dirs_to_clean.append(cls._default_storage_temp_dir)
    return Path(cls._default_storage_temp_dir.name)
reset_default_storage_dir() -> Path classmethod

Reset the default storage directly. This tears down and recreates the directory used by default for this client class when instantiating a client without explicitly providing a storage directory. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
57
58
59
60
61
62
63
64
65
@classmethod
def reset_default_storage_dir(cls) -> Path:
    """Reset the default storage directly. This tears down and recreates the directory used by
    default for this client class when instantiating a client without explicitly providing
    a storage directory. In this usage, "storage" refers to the local storage that simulates
    the cloud.
    """
    cls._default_storage_temp_dir = None
    return cls.get_default_storage_dir()
set_as_default_client() -> None

Set this client instance as the default one used when instantiating cloud path instances for this cloud without a client specified.

Source code in cloudpathlib/client.py 
106
107
108
109
def set_as_default_client(self) -> None:
    """Set this client instance as the default one used when instantiating cloud path
    instances for this cloud without a client specified."""
    self.__class__._default_client = self

LocalAzureBlobPath

Bases: LocalPath

Replacement for AzureBlobPath that uses the local file system. Intended as a monkeypatch substitute when writing tests.

Source code in cloudpathlib/local/implementations/azure.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
class LocalAzureBlobPath(LocalPath):
    """Replacement for AzureBlobPath that uses the local file system. Intended as a monkeypatch
    substitute when writing tests.
    """

    cloud_prefix: str = "az://"
    _cloud_meta = local_azure_blob_implementation

    @property
    def drive(self) -> str:
        return self.container

    def mkdir(self, parents=False, exist_ok=False, mode: Optional[Any] = None):
        # not possible to make empty directory on blob storage
        pass

    @property
    def container(self) -> str:
        return self._no_prefix.split("/", 1)[0]

    @property
    def blob(self) -> str:
        key = self._no_prefix_no_drive

        # key should never have starting slash for
        if key.startswith("/"):
            key = key[1:]

        return key

    @property
    def etag(self):
        return self.client._md5(self)

    @property
    def md5(self) -> str:
        return self.client._md5(self)

Attributes

anchor: str property
blob: str property
client: LocalClient instance-attribute
cloud_prefix: str = 'az://' class-attribute instance-attribute
container: str property
drive: str property
etag property
fspath: str property
md5: str property
name: str property
parent: Self property
parents: Tuple[Self, ...] property
parser: Self property
parts: Tuple[str, ...] property
stem: str property
suffix: str property
suffixes: List[str] property

Methods:

__init__(cloud_path: Union[str, Self, CloudPath], *parts: str, client: Optional[Client] = None) -> None
Source code in cloudpathlib/cloudpath.py 
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
def __init__(
    self,
    cloud_path: Union[str, Self, "CloudPath"],
    *parts: str,
    client: Optional["Client"] = None,
) -> None:
    # handle if local file gets opened. must be set at the top of the method in case any code
    # below raises an exception, this prevents __del__ from raising an AttributeError
    self._handle: Optional[IO] = None
    self._client: Optional["Client"] = None

    if parts:
        # ensure first part ends in "/"; (sometimes it is just prefix, sometimes a longer path)
        if not str(cloud_path).endswith("/"):
            cloud_path = str(cloud_path) + "/"

        cloud_path = str(cloud_path) + "/".join(p.strip("/") for p in parts)

    self.is_valid_cloudpath(cloud_path, raise_on_error=True)
    self._cloud_meta.validate_completeness()

    # 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):
            self._client = cloud_path.client
    else:
        self._client = client

    if client is not None and 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."
        )

    # track if local has been written to, if so it may need to be uploaded
    self._dirty = False
absolute() -> Self
Source code in cloudpathlib/cloudpath.py 
1012
1013
def absolute(self) -> Self:
    return self
as_uri() -> str
Source code in cloudpathlib/cloudpath.py 
444
445
def as_uri(self) -> str:
    return str(self)
as_url(presign: bool = False, expire_seconds: int = 60 * 60) -> str
Source code in cloudpathlib/cloudpath.py 
426
427
428
429
430
431
def as_url(self, presign: bool = False, expire_seconds: int = 60 * 60) -> str:
    if presign:
        url = self.client._generate_presigned_url(self, expire_seconds=expire_seconds)
    else:
        url = self.client._get_public_url(self)
    return url
clear_cache()

Removes cache if it exists

Source code in cloudpathlib/cloudpath.py 
1525
1526
1527
1528
1529
1530
1531
def clear_cache(self):
    """Removes cache if it exists"""
    if self._local.exists():
        if self._local.is_file():
            self._local.unlink()
        else:
            shutil.rmtree(self._local)
copy(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
copy(
    target: Self,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy(
    target: Path,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy(
    target: str,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self to target folder or file, if self is a file.

Source code in cloudpathlib/cloudpath.py 
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
def copy(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self to target folder or file, if self is a file."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )
copy_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
copy_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self into target directory, preserving the filename.

Source code in cloudpathlib/cloudpath.py 
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
def copy_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self into target directory, preserving the filename."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )
    return cast(Union[Path, Self], result)
copytree(destination, force_overwrite_to_cloud=None, ignore=None) 
copytree(
    destination: Self,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Self

copytree(
    destination: Path,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Path

copytree(
    destination: Union[str, os.PathLike, Self],
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Union[Path, CloudPath]

Copy self to a directory, if self is a directory.

Source code in cloudpathlib/cloudpath.py 
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
def copytree(self, destination, force_overwrite_to_cloud=None, ignore=None):
    """Copy self to a directory, if self is a directory."""
    if not self.is_dir():
        raise CloudPathNotADirectoryError(
            f"Origin path {self} must be a directory. To copy a single file use the method copy."
        )

    destination = anypath.to_anypath(destination)

    if destination.exists() and destination.is_file():
        raise CloudPathFileExistsError(
            f"Destination path {destination} of copytree must be a directory."
        )

    contents = list(self.iterdir())

    if ignore is not None:
        ignored_names = ignore(self._no_prefix_no_drive, [x.name for x in contents])
    else:
        ignored_names = set()

    destination.mkdir(parents=True, exist_ok=True)

    for subpath in contents:
        if subpath.name in ignored_names:
            continue
        if subpath.is_file():
            subpath.copy(
                destination / subpath.name, force_overwrite_to_cloud=force_overwrite_to_cloud
            )
        elif subpath.is_dir():
            subpath.copytree(
                destination / (subpath.name + ("" if subpath.name.endswith("/") else "/")),
                force_overwrite_to_cloud=force_overwrite_to_cloud,
                ignore=ignore,
            )

    return destination
download_to(destination: Union[str, os.PathLike]) -> Path
Source code in cloudpathlib/cloudpath.py 
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
def download_to(self, destination: Union[str, os.PathLike]) -> Path:
    destination = Path(destination)

    if not self.exists():
        raise CloudPathNotExistsError(f"Cannot download because path does not exist: {self}")

    if self.is_file():
        if destination.is_dir():
            destination = destination / self.name
        return 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)

        return destination
exists(follow_symlinks=True) -> bool
Source code in cloudpathlib/cloudpath.py 
447
448
def exists(self, follow_symlinks=True) -> bool:
    return self.client._exists(self)
from_uri(uri: str) -> Self classmethod
Source code in cloudpathlib/cloudpath.py 
460
461
462
@classmethod
def from_uri(cls, uri: str) -> Self:
    return cls(uri)
full_match(pattern: str, case_sensitive: Optional[bool] = None) -> bool
Source code in cloudpathlib/cloudpath.py 
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
def full_match(self, pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    if sys.version_info < (3, 13):
        raise NotImplementedError("full_match requires Python 3.13 or higher")

    # strip scheme from start of pattern before testing
    if pattern.startswith(self.anchor + self.drive):
        pattern = pattern[len(self.anchor + self.drive) :]
    elif pattern.startswith(self.anchor):
        # for http paths, keep leading slash
        pattern = pattern[len(self.anchor) - 1 :]

    # remove drive, which is kept on normal dispatch to pathlib
    return PurePosixPath(self._no_prefix_no_drive).full_match(  # type: ignore[attr-defined]
        pattern, case_sensitive=case_sensitive
    )
glob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]
Source code in cloudpathlib/cloudpath.py 
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
def glob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(
        selector,
        "/" in pattern
        or "**"
        in pattern,  # recursive listing needed if explicit ** or any sub folder in pattern
    )
info() -> CloudPathInfo

Return a CloudPathInfo object for this path.

Source code in cloudpathlib/cloudpath.py 
1163
1164
1165
def info(self) -> "CloudPathInfo":
    """Return a CloudPathInfo object for this path."""
    return CloudPathInfo(self)
is_absolute() -> bool
Source code in cloudpathlib/cloudpath.py 
1015
1016
def is_absolute(self) -> bool:
    return True
is_dir(follow_symlinks=True) -> bool
Source code in cloudpathlib/local/localpath.py 
15
16
def is_dir(self, follow_symlinks=True) -> bool:
    return self.client._is_dir(self, follow_symlinks=follow_symlinks)
is_file(follow_symlinks=True) -> bool
Source code in cloudpathlib/local/localpath.py 
18
19
def is_file(self, follow_symlinks=True) -> bool:
    return self.client._is_file(self, follow_symlinks=follow_symlinks)
is_junction()
Source code in cloudpathlib/cloudpath.py 
959
960
def is_junction(self):
    return False  # only windows paths can be junctions, not cloudpaths
is_relative_to(other: Self) -> bool
Source code in cloudpathlib/cloudpath.py 
1038
1039
1040
1041
1042
1043
def is_relative_to(self, other: Self) -> bool:
    try:
        self.relative_to(other)
        return True
    except ValueError:
        return False
is_valid_cloudpath(path: Union[str, CloudPath], raise_on_error: bool = False) -> Union[bool, TypeGuard[Self]] classmethod 
is_valid_cloudpath(
    path: CloudPath, raise_on_error: bool = ...
) -> TypeGuard[Self]

is_valid_cloudpath(
    path: str, raise_on_error: bool = ...
) -> bool
Source code in cloudpathlib/cloudpath.py 
332
333
334
335
336
337
338
339
340
341
342
343
@classmethod
def is_valid_cloudpath(
    cls, path: Union[str, "CloudPath"], raise_on_error: bool = False
) -> Union[bool, TypeGuard[Self]]:
    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() -> Generator[Self, None, None]
Source code in cloudpathlib/cloudpath.py 
579
580
581
582
def iterdir(self) -> Generator[Self, None, None]:
    for f, _ in self.client._list_dir(self, recursive=False):
        if f != self:  # iterdir does not include itself in pathlib
            yield f
joinpath(*pathsegments: Union[str, os.PathLike]) -> Self
Source code in cloudpathlib/cloudpath.py 
1009
1010
def joinpath(self, *pathsegments: Union[str, os.PathLike]) -> Self:
    return self._dispatch_to_path("joinpath", *pathsegments)
match(path_pattern: str, case_sensitive: Optional[bool] = None) -> bool
Source code in cloudpathlib/cloudpath.py 
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
def match(self, path_pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    # 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 + "/") :]

    kwargs = dict(case_sensitive=case_sensitive)

    if sys.version_info < (3, 12):
        kwargs.pop("case_sensitive")

    return self._dispatch_to_path("match", path_pattern, **kwargs)
mkdir(parents=False, exist_ok=False, mode: Optional[Any] = None)
Source code in cloudpathlib/local/implementations/azure.py 
52
53
54
def mkdir(self, parents=False, exist_ok=False, mode: Optional[Any] = None):
    # not possible to make empty directory on blob storage
    pass
move(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
move(
    target: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move(
    target: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move(
    target: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self to target location, removing the source.

Source code in cloudpathlib/cloudpath.py 
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
def move(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self to target location, removing the source."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )
move_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
move_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self into target directory, preserving the filename and removing the source.

Source code in cloudpathlib/cloudpath.py 
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
def move_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self into target directory, preserving the filename and removing the source."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )
    return cast(Union[Path, Self], result)
open(mode: str = 'r', buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, force_overwrite_from_cloud: Optional[bool] = None, force_overwrite_to_cloud: Optional[bool] = None) -> IO[Any] 
open(
    mode: OpenTextMode = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> TextIOWrapper

open(
    mode: OpenBinaryMode,
    buffering: Literal[0],
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> FileIO

open(
    mode: OpenBinaryModeUpdating,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedRandom

open(
    mode: OpenBinaryModeWriting,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedWriter

open(
    mode: OpenBinaryModeReading,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedReader

open(
    mode: OpenBinaryMode,
    buffering: int = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BinaryIO

open(
    mode: str,
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> IO[Any]
Source code in cloudpathlib/cloudpath.py 
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
def open(
    self,
    mode: str = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
    force_overwrite_to_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
) -> "IO[Any]":
    # if trying to call open on a directory that exists
    exists_on_cloud = self.exists()

    if exists_on_cloud and not self.is_file():
        raise CloudPathIsADirectoryError(
            f"Cannot open directory, only files. Tried to open ({self})"
        )

    if not exists_on_cloud and any(m in mode for m in ("r", "a")):
        raise CloudPathFileNotFoundError(
            f"File opened for read or append, but it does not exist on cloud: {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.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
        wrapped_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_upload(*args, **kwargs) -> None:
            wrapped_close(*args, **kwargs)

            # we should be idempotent and not upload again if
            # we already ran our close method patch
            if not self._dirty:
                return

            # 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)
            self._dirty = False

        buffer.close = _patched_close_upload  # type: ignore

        # 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

    # if we don't want any cache around, remove the cache
    # as soon as the file is closed
    if self.client.file_cache_mode == FileCacheMode.close_file:
        # this may be _patched_close_upload, in which case we need to
        # make sure to call that first so the file gets uploaded
        wrapped_close_for_cache = buffer.close

        def _patched_close_empty_cache(*args, **kwargs):
            wrapped_close_for_cache(*args, **kwargs)

            # remove local file as last step on closing
            self.clear_cache()

        buffer.close = _patched_close_empty_cache  # type: ignore

    return buffer
read_bytes() -> bytes
Source code in cloudpathlib/cloudpath.py 
946
947
948
def read_bytes(self) -> bytes:
    with self.open(mode="rb") as f:
        return f.read()
read_text(encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> str
Source code in cloudpathlib/cloudpath.py 
950
951
952
953
954
955
956
957
def read_text(
    self,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> str:
    with self.open(mode="r", encoding=encoding, errors=errors, newline=newline) as f:
        return f.read()
relative_to(other: Self, walk_up: bool = False) -> PurePosixPath
Source code in cloudpathlib/cloudpath.py 
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
def relative_to(self, other: Self, walk_up: bool = False) -> PurePosixPath:
    # We don't dispatch regularly since this never returns a cloud path (since it is relative, and cloud paths are
    # absolute)
    if not isinstance(other, CloudPath):
        raise ValueError(f"{self} is a cloud path, but {other} is not")
    if self.anchor != other.anchor:
        raise ValueError(
            f"{self} is a {self.anchor} path, but {other} is a {other.anchor} path"
        )

    kwargs = dict(walk_up=walk_up)

    if sys.version_info < (3, 12):
        kwargs.pop("walk_up")

    return self._path.relative_to(other._path, **kwargs)  # type: ignore[call-arg]
rename(target: Self) -> Self
Source code in cloudpathlib/cloudpath.py 
886
887
888
889
def rename(self, target: Self) -> Self:
    # for cloud services replace == rename since we don't just rename,
    # we actually move files
    return self.replace(target)
replace(target: Self) -> Self
Source code in cloudpathlib/cloudpath.py 
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
def replace(self, target: Self) -> Self:
    if type(self) is not type(target):
        raise TypeError(
            f"The target based to rename must be an instantiated class of type: {type(self)}"
        )

    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; rename/replace the files recursively."
        )

    if target == self:
        # Request is to replace/rename this with the same path - nothing to do
        return self

    if target.exists():
        target.unlink()

    self.client._move_file(self, target)
    return target
resolve(strict: bool = False) -> Self
Source code in cloudpathlib/cloudpath.py 
1018
1019
def resolve(self, strict: bool = False) -> Self:
    return self
rglob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]
Source code in cloudpathlib/cloudpath.py 
564
565
566
567
568
569
570
571
572
573
574
575
576
577
def rglob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        ("**",) + tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(selector, True)
rmdir() -> None
Source code in cloudpathlib/cloudpath.py 
891
892
893
894
895
896
897
898
899
900
901
902
903
def rmdir(self) -> None:
    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() -> None

Delete an entire directory tree.

Source code in cloudpathlib/cloudpath.py 
1190
1191
1192
1193
1194
1195
1196
def rmtree(self) -> None:
    """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(other_path: Union[str, os.PathLike]) -> bool
Source code in cloudpathlib/cloudpath.py 
905
906
907
def samefile(self, other_path: Union[str, os.PathLike]) -> bool:
    # all cloud paths are absolute and the paths are used for hash
    return self == other_path
stat(follow_symlinks=True)
Source code in cloudpathlib/local/localpath.py 
21
22
23
24
25
26
27
28
def stat(self, follow_symlinks=True):
    try:
        meta = self.client._stat(self)
    except FileNotFoundError:
        raise NoStatError(
            f"No stats available for {self}; it may be a directory or not exist."
        )
    return meta
touch(exist_ok: bool = True, mode: Optional[Any] = None)
Source code in cloudpathlib/local/localpath.py 
30
31
def touch(self, exist_ok: bool = True, mode: Optional[Any] = None):
    self.client._touch(self, exist_ok)
Source code in cloudpathlib/cloudpath.py 
909
910
911
912
913
914
915
def unlink(self, missing_ok: bool = True) -> None:
    # Note: missing_ok defaults to False in pathlib, but changing the default now would be a breaking change.
    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; call rmdir instead of unlink."
        )
    self.client._remove(self, missing_ok)
upload_from(source: Union[str, os.PathLike], force_overwrite_to_cloud: Optional[bool] = None) -> Self

Upload a file or directory to the cloud path.

Source code in cloudpathlib/cloudpath.py 
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
def upload_from(
    self,
    source: Union[str, os.PathLike],
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self:
    """Upload a file or directory to the cloud path."""
    source = Path(source)

    if source.is_dir():
        for p in source.iterdir():
            (self / p.name).upload_from(p, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return self

    else:
        if self.exists() and self.is_dir():
            dst = self / source.name
        else:
            dst = self

        dst._upload_file_to_cloud(source, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return dst
validate(v: str) -> Self classmethod

Used as a Pydantic validator. See https://docs.pydantic.dev/2.0/usage/types/custom/

Source code in cloudpathlib/cloudpath.py 
1687
1688
1689
1690
1691
@classmethod
def validate(cls, v: str) -> Self:
    """Used as a Pydantic validator. See
    https://docs.pydantic.dev/2.0/usage/types/custom/"""
    return cls(v)
walk(top_down: bool = True, on_error: Optional[Callable] = None, follow_symlinks: bool = False, lazy: bool = False) -> Generator[Tuple[Self, List[str], List[str]], None, None]

Walk the directory tree rooted at this path, similar to :meth:pathlib.Path.walk and :func:os.walk.

By default (lazy=False) the entire subtree is listed up front with a single recursive listing, which is the fastest option for a full walk on cloud backends.

Pass lazy=True to defer listing until each directory is visited (one non-recursive listing per directory). This is slower for a full walk, but lets callers prune dirnames in place (when top_down=True) to avoid fetching the contents of skipped subtrees entirely -- which can be dramatically faster and cheaper for sparse traversals.

follow_symlinks is accepted for signature parity with pathlib but has no effect on cloud backends, which do not have symlinks.

Source code in cloudpathlib/cloudpath.py 
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def walk(
    self,
    top_down: bool = True,
    on_error: Optional[Callable] = None,
    follow_symlinks: bool = False,
    lazy: bool = False,
) -> Generator[Tuple[Self, List[str], List[str]], None, None]:
    """Walk the directory tree rooted at this path, similar to
    :meth:`pathlib.Path.walk` and :func:`os.walk`.

    By default (``lazy=False``) the entire subtree is listed up front with a
    single recursive listing, which is the fastest option for a full walk on
    cloud backends.

    Pass ``lazy=True`` to defer listing until each directory is visited (one
    non-recursive listing per directory). This is slower for a full walk,
    but lets callers prune ``dirnames`` in place (when ``top_down=True``) to
    avoid fetching the contents of skipped subtrees entirely -- which can be
    dramatically faster and cheaper for sparse traversals.

    ``follow_symlinks`` is accepted for signature parity with ``pathlib``
    but has no effect on cloud backends, which do not have symlinks.
    """
    if lazy:
        yield from self._walk_lazy(top_down=top_down, on_error=on_error)
        return

    try:
        file_tree = self._build_subtree(recursive=True)  # walking is always recursive
        yield from self._walk_results_from_tree(self, file_tree, top_down=top_down)

    except Exception as e:
        if on_error is not None:
            on_error(e)
        else:
            raise
with_name(name: str) -> Self
Source code in cloudpathlib/cloudpath.py 
1119
1120
def with_name(self, name: str) -> Self:
    return self._dispatch_to_path("with_name", name)
with_segments(*pathsegments) -> Self

Create a new CloudPath with the same client out of the given segments. The first segment will be interpreted as the bucket/container name.

Source code in cloudpathlib/cloudpath.py 
1122
1123
1124
1125
1126
def with_segments(self, *pathsegments) -> Self:
    """Create a new CloudPath with the same client out of the given segments.
    The first segment will be interpreted as the bucket/container name.
    """
    return self._new_cloudpath("/".join(pathsegments))
with_stem(stem: str) -> Self
Source code in cloudpathlib/cloudpath.py 
1112
1113
1114
1115
1116
1117
def with_stem(self, stem: str) -> Self:
    try:
        return self._dispatch_to_path("with_stem", stem)
    except AttributeError:
        # with_stem was only added in python 3.9, so we fallback for compatibility
        return self.with_name(stem + self.suffix)
with_suffix(suffix: str) -> Self
Source code in cloudpathlib/cloudpath.py 
1128
1129
def with_suffix(self, suffix: str) -> Self:
    return self._dispatch_to_path("with_suffix", suffix)
write_bytes(data: bytes) -> int

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

Source code in cloudpathlib/cloudpath.py 
917
918
919
920
921
922
923
924
925
926
def write_bytes(self, data: bytes) -> int:
    """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(data: str, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> int

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.10/Lib/pathlib.py#L1146-L1155

Source code in cloudpathlib/cloudpath.py 
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
def write_text(
    self,
    data: str,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> int:
    """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.10/Lib/pathlib.py#L1146-L1155
    """
    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, newline=newline) as f:
        return f.write(data)

LocalClient

Bases: Client

Abstract client for accessing objects the local filesystem. Subclasses are as a monkeypatch substitutes for normal Client subclasses when writing tests.

Source code in cloudpathlib/local/localclient.py 
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
class LocalClient(Client):
    """Abstract client for accessing objects the local filesystem. Subclasses are as a monkeypatch
    substitutes for normal Client subclasses when writing tests."""

    # Class-level variable to tracks the default storage directory for this client class
    # that is used if a client is instantiated without a directory being explicitly provided
    _default_storage_temp_dir: ClassVar[Optional[TemporaryDirectory]] = None

    # Instance-level variable that tracks the local storage directory for this client
    _local_storage_dir: Optional[Union[str, os.PathLike]]

    def __init__(
        self,
        *args,
        local_storage_dir: Optional[Union[str, os.PathLike]] = None,
        file_cache_mode: Optional[Union[str, FileCacheMode]] = None,
        local_cache_dir: Optional[Union[str, os.PathLike]] = None,
        content_type_method: Optional[Callable] = mimetypes.guess_type,
        **kwargs,
    ):
        self._local_storage_dir = local_storage_dir

        super().__init__(
            local_cache_dir=local_cache_dir,
            content_type_method=content_type_method,
            file_cache_mode=file_cache_mode,
        )

    @classmethod
    def get_default_storage_dir(cls) -> Path:
        """Return the default storage directory for this client class. This is used if a client
        is instantiated without a storage directory being explicitly provided. In this usage,
        "storage" refers to the local storage that simulates the cloud.
        """
        if cls._default_storage_temp_dir is None:
            cls._default_storage_temp_dir = TemporaryDirectory()
            _temp_dirs_to_clean.append(cls._default_storage_temp_dir)
        return Path(cls._default_storage_temp_dir.name)

    @classmethod
    def reset_default_storage_dir(cls) -> Path:
        """Reset the default storage directly. This tears down and recreates the directory used by
        default for this client class when instantiating a client without explicitly providing
        a storage directory. In this usage, "storage" refers to the local storage that simulates
        the cloud.
        """
        cls._default_storage_temp_dir = None
        return cls.get_default_storage_dir()

    @property
    def local_storage_dir(self) -> Path:
        """The local directory where files are stored for this client. This storage directory is
        the one that simulates the cloud. If no storage directory was provided on instantiating the
        client, the default storage directory for this client class is used.
        """
        if self._local_storage_dir is None:
            # No explicit local storage was provided on instantiating the client.
            # Use the default storage directory for this class.
            return self.get_default_storage_dir()
        return Path(self._local_storage_dir)

    def _cloud_path_to_local(self, cloud_path: "LocalPath") -> Path:
        return self.local_storage_dir / cloud_path._no_prefix

    def _local_to_cloud_path(self, local_path: Union[str, os.PathLike]) -> "LocalPath":
        local_path = Path(local_path)
        cloud_prefix = self._cloud_meta.path_class.cloud_prefix
        return self.CloudPath(
            f"{cloud_prefix}{PurePosixPath(local_path.relative_to(self.local_storage_dir))}"
        )

    def _download_file(self, cloud_path: "LocalPath", local_path: Union[str, os.PathLike]) -> Path:
        local_path = Path(local_path)
        local_path.parent.mkdir(exist_ok=True, parents=True)

        try:
            shutil.copyfile(self._cloud_path_to_local(cloud_path), local_path)
        except FileNotFoundError:
            # erroneous FileNotFoundError appears in tests sometimes; patiently insist on the parent directory existing
            sleep(1.0)
            local_path.parent.mkdir(exist_ok=True, parents=True)
            sleep(1.0)

            shutil.copyfile(self._cloud_path_to_local(cloud_path), local_path)

        return local_path

    def _exists(self, cloud_path: "LocalPath") -> bool:
        return self._cloud_path_to_local(cloud_path).exists()

    def _is_dir(self, cloud_path: "LocalPath", follow_symlinks=True) -> bool:
        kwargs = dict(follow_symlinks=follow_symlinks)
        if sys.version_info < (3, 13):
            kwargs.pop("follow_symlinks")

        return self._cloud_path_to_local(cloud_path).is_dir(**kwargs)

    def _is_file(self, cloud_path: "LocalPath", follow_symlinks=True) -> bool:
        kwargs = dict(follow_symlinks=follow_symlinks)
        if sys.version_info < (3, 13):
            kwargs.pop("follow_symlinks")

        return self._cloud_path_to_local(cloud_path).is_file(**kwargs)

    def _is_file_or_dir(self, cloud_path: "LocalPath") -> Optional[str]:
        if self._is_dir(cloud_path):
            return "dir"
        elif self._is_file(cloud_path):
            return "file"
        else:
            raise FileNotFoundError(f"Path could not be identified as file or dir: {cloud_path}")

    def _list_dir(
        self, cloud_path: "LocalPath", recursive=False
    ) -> Iterable[Tuple["LocalPath", bool]]:
        pattern = "**/*" if recursive else "*"
        for obj in self._cloud_path_to_local(cloud_path).glob(pattern):
            yield (self._local_to_cloud_path(obj), obj.is_dir())

    def _md5(self, cloud_path: "LocalPath") -> str:
        return md5(self._cloud_path_to_local(cloud_path).read_bytes()).hexdigest()

    def _move_file(
        self, src: "LocalPath", dst: "LocalPath", remove_src: bool = True
    ) -> "LocalPath":
        self._cloud_path_to_local(dst).parent.mkdir(exist_ok=True, parents=True)

        if remove_src:
            self._cloud_path_to_local(src).replace(self._cloud_path_to_local(dst))
        else:
            shutil.copy(self._cloud_path_to_local(src), self._cloud_path_to_local(dst))
        return dst

    def _remove(self, cloud_path: "LocalPath", missing_ok: bool = True) -> None:
        local_storage_path = self._cloud_path_to_local(cloud_path)
        if not missing_ok and not local_storage_path.exists():
            raise FileNotFoundError(f"File does not exist: {cloud_path}")

        if local_storage_path.is_file():
            local_storage_path.unlink()
        elif local_storage_path.is_dir():
            shutil.rmtree(local_storage_path)

    def _stat(self, cloud_path: "LocalPath") -> os.stat_result:
        stat_result = self._cloud_path_to_local(cloud_path).stat()

        return os.stat_result(
            (  # type: ignore
                None,  # type: ignore # mode
                None,  # ino
                cloud_path.cloud_prefix,  # dev,
                None,  # nlink,
                None,  # uid,
                None,  # gid,
                stat_result.st_size,  # size,
                None,  # atime,
                stat_result.st_mtime,  # mtime,
                None,  # ctime,
            )
        )

    def _touch(self, cloud_path: "LocalPath", exist_ok: bool = True) -> None:
        local_storage_path = self._cloud_path_to_local(cloud_path)
        if local_storage_path.exists() and not exist_ok:
            raise FileExistsError(f"File exists: {cloud_path}")
        local_storage_path.parent.mkdir(exist_ok=True, parents=True)
        local_storage_path.touch()

    def _upload_file(
        self, local_path: Union[str, os.PathLike], cloud_path: "LocalPath"
    ) -> "LocalPath":
        dst = self._cloud_path_to_local(cloud_path)
        dst.parent.mkdir(exist_ok=True, parents=True)
        shutil.copy(local_path, dst)
        return cloud_path

    def _get_metadata(self, cloud_path: "LocalPath") -> Dict:
        # content_type is the only metadata we test currently
        if self.content_type_method is None:
            content_type_method = lambda x: (None, None)
        else:
            content_type_method = self.content_type_method

        return {
            "content_type": content_type_method(str(self._cloud_path_to_local(cloud_path)))[0],
        }

    def _get_public_url(self, cloud_path: "LocalPath") -> str:
        return cloud_path.as_uri()

    def _generate_presigned_url(
        self, cloud_path: "LocalPath", expire_seconds: int = 60 * 60
    ) -> str:
        public_url = self._get_public_url(cloud_path)
        parts = urlsplit(public_url)
        query = dict(parse_qsl(parts.query, keep_blank_values=True))
        query["expires"] = str(expire_seconds)
        query["signature"] = "local"
        return urlunsplit(parts._replace(query=urlencode(query)))

Attributes

content_type_method = content_type_method instance-attribute
file_cache_mode = file_cache_mode instance-attribute
local_storage_dir: Path property

The local directory where files are stored for this client. This storage directory is the one that simulates the cloud. If no storage directory was provided on instantiating the client, the default storage directory for this client class is used.

Methods:

CloudPath(cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath
Source code in cloudpathlib/client.py 
111
112
def CloudPath(self, cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath:
    return self._cloud_meta.path_class(cloud_path, *parts, client=self)  # type: ignore
__init__(*args, local_storage_dir: Optional[Union[str, os.PathLike]] = None, file_cache_mode: Optional[Union[str, FileCacheMode]] = None, local_cache_dir: Optional[Union[str, os.PathLike]] = None, content_type_method: Optional[Callable] = mimetypes.guess_type, **kwargs)
Source code in cloudpathlib/local/localclient.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def __init__(
    self,
    *args,
    local_storage_dir: Optional[Union[str, os.PathLike]] = None,
    file_cache_mode: Optional[Union[str, FileCacheMode]] = None,
    local_cache_dir: Optional[Union[str, os.PathLike]] = None,
    content_type_method: Optional[Callable] = mimetypes.guess_type,
    **kwargs,
):
    self._local_storage_dir = local_storage_dir

    super().__init__(
        local_cache_dir=local_cache_dir,
        content_type_method=content_type_method,
        file_cache_mode=file_cache_mode,
    )
clear_cache()

Clears the contents of the cache folder. Does not remove folder so it can keep being written to.

Source code in cloudpathlib/client.py 
114
115
116
117
118
119
120
121
122
123
def clear_cache(self):
    """Clears the contents of the cache folder.
    Does not remove folder so it can keep being written to.
    """
    if self._local_cache_dir.exists():
        for p in self._local_cache_dir.iterdir():
            if p.is_file():
                p.unlink()
            else:
                shutil.rmtree(p)
get_default_client() -> Client[BoundedCloudPath] classmethod

Get the default client, which the one that is used when instantiating a cloud path instance for this cloud without a client specified.

Source code in cloudpathlib/client.py 
 97
 98
 99
100
101
102
103
104
@classmethod
def get_default_client(cls) -> "Client[BoundedCloudPath]":
    """Get the default client, which the one that is used when instantiating a cloud path
    instance for this cloud without a client specified.
    """
    if cls._default_client is None:
        cls._default_client = cls()
    return cls._default_client
get_default_storage_dir() -> Path classmethod

Return the default storage directory for this client class. This is used if a client is instantiated without a storage directory being explicitly provided. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
46
47
48
49
50
51
52
53
54
55
@classmethod
def get_default_storage_dir(cls) -> Path:
    """Return the default storage directory for this client class. This is used if a client
    is instantiated without a storage directory being explicitly provided. In this usage,
    "storage" refers to the local storage that simulates the cloud.
    """
    if cls._default_storage_temp_dir is None:
        cls._default_storage_temp_dir = TemporaryDirectory()
        _temp_dirs_to_clean.append(cls._default_storage_temp_dir)
    return Path(cls._default_storage_temp_dir.name)
reset_default_storage_dir() -> Path classmethod

Reset the default storage directly. This tears down and recreates the directory used by default for this client class when instantiating a client without explicitly providing a storage directory. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
57
58
59
60
61
62
63
64
65
@classmethod
def reset_default_storage_dir(cls) -> Path:
    """Reset the default storage directly. This tears down and recreates the directory used by
    default for this client class when instantiating a client without explicitly providing
    a storage directory. In this usage, "storage" refers to the local storage that simulates
    the cloud.
    """
    cls._default_storage_temp_dir = None
    return cls.get_default_storage_dir()
set_as_default_client() -> None

Set this client instance as the default one used when instantiating cloud path instances for this cloud without a client specified.

Source code in cloudpathlib/client.py 
106
107
108
109
def set_as_default_client(self) -> None:
    """Set this client instance as the default one used when instantiating cloud path
    instances for this cloud without a client specified."""
    self.__class__._default_client = self

LocalGSClient

Bases: LocalClient

Replacement for GSClient that uses the local file system. Intended as a monkeypatch substitute when writing tests.

Source code in cloudpathlib/local/implementations/gs.py 
11
12
13
14
15
16
class LocalGSClient(LocalClient):
    """Replacement for GSClient that uses the local file system. Intended as a monkeypatch
    substitute when writing tests.
    """

    _cloud_meta = local_gs_implementation

Attributes

content_type_method = content_type_method instance-attribute
file_cache_mode = file_cache_mode instance-attribute
local_storage_dir: Path property

The local directory where files are stored for this client. This storage directory is the one that simulates the cloud. If no storage directory was provided on instantiating the client, the default storage directory for this client class is used.

Methods:

CloudPath(cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath
Source code in cloudpathlib/client.py 
111
112
def CloudPath(self, cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath:
    return self._cloud_meta.path_class(cloud_path, *parts, client=self)  # type: ignore
__init__(*args, local_storage_dir: Optional[Union[str, os.PathLike]] = None, file_cache_mode: Optional[Union[str, FileCacheMode]] = None, local_cache_dir: Optional[Union[str, os.PathLike]] = None, content_type_method: Optional[Callable] = mimetypes.guess_type, **kwargs)
Source code in cloudpathlib/local/localclient.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def __init__(
    self,
    *args,
    local_storage_dir: Optional[Union[str, os.PathLike]] = None,
    file_cache_mode: Optional[Union[str, FileCacheMode]] = None,
    local_cache_dir: Optional[Union[str, os.PathLike]] = None,
    content_type_method: Optional[Callable] = mimetypes.guess_type,
    **kwargs,
):
    self._local_storage_dir = local_storage_dir

    super().__init__(
        local_cache_dir=local_cache_dir,
        content_type_method=content_type_method,
        file_cache_mode=file_cache_mode,
    )
clear_cache()

Clears the contents of the cache folder. Does not remove folder so it can keep being written to.

Source code in cloudpathlib/client.py 
114
115
116
117
118
119
120
121
122
123
def clear_cache(self):
    """Clears the contents of the cache folder.
    Does not remove folder so it can keep being written to.
    """
    if self._local_cache_dir.exists():
        for p in self._local_cache_dir.iterdir():
            if p.is_file():
                p.unlink()
            else:
                shutil.rmtree(p)
get_default_client() -> Client[BoundedCloudPath] classmethod

Get the default client, which the one that is used when instantiating a cloud path instance for this cloud without a client specified.

Source code in cloudpathlib/client.py 
 97
 98
 99
100
101
102
103
104
@classmethod
def get_default_client(cls) -> "Client[BoundedCloudPath]":
    """Get the default client, which the one that is used when instantiating a cloud path
    instance for this cloud without a client specified.
    """
    if cls._default_client is None:
        cls._default_client = cls()
    return cls._default_client
get_default_storage_dir() -> Path classmethod

Return the default storage directory for this client class. This is used if a client is instantiated without a storage directory being explicitly provided. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
46
47
48
49
50
51
52
53
54
55
@classmethod
def get_default_storage_dir(cls) -> Path:
    """Return the default storage directory for this client class. This is used if a client
    is instantiated without a storage directory being explicitly provided. In this usage,
    "storage" refers to the local storage that simulates the cloud.
    """
    if cls._default_storage_temp_dir is None:
        cls._default_storage_temp_dir = TemporaryDirectory()
        _temp_dirs_to_clean.append(cls._default_storage_temp_dir)
    return Path(cls._default_storage_temp_dir.name)
reset_default_storage_dir() -> Path classmethod

Reset the default storage directly. This tears down and recreates the directory used by default for this client class when instantiating a client without explicitly providing a storage directory. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
57
58
59
60
61
62
63
64
65
@classmethod
def reset_default_storage_dir(cls) -> Path:
    """Reset the default storage directly. This tears down and recreates the directory used by
    default for this client class when instantiating a client without explicitly providing
    a storage directory. In this usage, "storage" refers to the local storage that simulates
    the cloud.
    """
    cls._default_storage_temp_dir = None
    return cls.get_default_storage_dir()
set_as_default_client() -> None

Set this client instance as the default one used when instantiating cloud path instances for this cloud without a client specified.

Source code in cloudpathlib/client.py 
106
107
108
109
def set_as_default_client(self) -> None:
    """Set this client instance as the default one used when instantiating cloud path
    instances for this cloud without a client specified."""
    self.__class__._default_client = self

LocalGSPath

Bases: LocalPath

Replacement for GSPath that uses the local file system. Intended as a monkeypatch substitute when writing tests.

Source code in cloudpathlib/local/implementations/gs.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
class LocalGSPath(LocalPath):
    """Replacement for GSPath that uses the local file system. Intended as a monkeypatch substitute
    when writing tests.
    """

    cloud_prefix: str = "gs://"
    _cloud_meta = local_gs_implementation

    @property
    def drive(self) -> str:
        return self.bucket

    def mkdir(self, parents=False, exist_ok=False, mode: Optional[Any] = None):
        # not possible to make empty directory on gs
        pass

    @property
    def bucket(self) -> str:
        return self._no_prefix.split("/", 1)[0]

    @property
    def blob(self) -> str:
        key = self._no_prefix_no_drive

        # key should never have starting slash for
        # use with boto, etc.
        if key.startswith("/"):
            key = key[1:]

        return key

    @property
    def etag(self):
        return self.client._md5(self)

    @property
    def md5(self) -> str:
        return self.client._md5(self)

Attributes

anchor: str property
blob: str property
bucket: str property
client: LocalClient instance-attribute
cloud_prefix: str = 'gs://' class-attribute instance-attribute
drive: str property
etag property
fspath: str property
md5: str property
name: str property
parent: Self property
parents: Tuple[Self, ...] property
parser: Self property
parts: Tuple[str, ...] property
stem: str property
suffix: str property
suffixes: List[str] property

Methods:

__init__(cloud_path: Union[str, Self, CloudPath], *parts: str, client: Optional[Client] = None) -> None
Source code in cloudpathlib/cloudpath.py 
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
def __init__(
    self,
    cloud_path: Union[str, Self, "CloudPath"],
    *parts: str,
    client: Optional["Client"] = None,
) -> None:
    # handle if local file gets opened. must be set at the top of the method in case any code
    # below raises an exception, this prevents __del__ from raising an AttributeError
    self._handle: Optional[IO] = None
    self._client: Optional["Client"] = None

    if parts:
        # ensure first part ends in "/"; (sometimes it is just prefix, sometimes a longer path)
        if not str(cloud_path).endswith("/"):
            cloud_path = str(cloud_path) + "/"

        cloud_path = str(cloud_path) + "/".join(p.strip("/") for p in parts)

    self.is_valid_cloudpath(cloud_path, raise_on_error=True)
    self._cloud_meta.validate_completeness()

    # 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):
            self._client = cloud_path.client
    else:
        self._client = client

    if client is not None and 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."
        )

    # track if local has been written to, if so it may need to be uploaded
    self._dirty = False
absolute() -> Self
Source code in cloudpathlib/cloudpath.py 
1012
1013
def absolute(self) -> Self:
    return self
as_uri() -> str
Source code in cloudpathlib/cloudpath.py 
444
445
def as_uri(self) -> str:
    return str(self)
as_url(presign: bool = False, expire_seconds: int = 60 * 60) -> str
Source code in cloudpathlib/cloudpath.py 
426
427
428
429
430
431
def as_url(self, presign: bool = False, expire_seconds: int = 60 * 60) -> str:
    if presign:
        url = self.client._generate_presigned_url(self, expire_seconds=expire_seconds)
    else:
        url = self.client._get_public_url(self)
    return url
clear_cache()

Removes cache if it exists

Source code in cloudpathlib/cloudpath.py 
1525
1526
1527
1528
1529
1530
1531
def clear_cache(self):
    """Removes cache if it exists"""
    if self._local.exists():
        if self._local.is_file():
            self._local.unlink()
        else:
            shutil.rmtree(self._local)
copy(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
copy(
    target: Self,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy(
    target: Path,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy(
    target: str,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self to target folder or file, if self is a file.

Source code in cloudpathlib/cloudpath.py 
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
def copy(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self to target folder or file, if self is a file."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )
copy_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
copy_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self into target directory, preserving the filename.

Source code in cloudpathlib/cloudpath.py 
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
def copy_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self into target directory, preserving the filename."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )
    return cast(Union[Path, Self], result)
copytree(destination, force_overwrite_to_cloud=None, ignore=None) 
copytree(
    destination: Self,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Self

copytree(
    destination: Path,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Path

copytree(
    destination: Union[str, os.PathLike, Self],
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Union[Path, CloudPath]

Copy self to a directory, if self is a directory.

Source code in cloudpathlib/cloudpath.py 
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
def copytree(self, destination, force_overwrite_to_cloud=None, ignore=None):
    """Copy self to a directory, if self is a directory."""
    if not self.is_dir():
        raise CloudPathNotADirectoryError(
            f"Origin path {self} must be a directory. To copy a single file use the method copy."
        )

    destination = anypath.to_anypath(destination)

    if destination.exists() and destination.is_file():
        raise CloudPathFileExistsError(
            f"Destination path {destination} of copytree must be a directory."
        )

    contents = list(self.iterdir())

    if ignore is not None:
        ignored_names = ignore(self._no_prefix_no_drive, [x.name for x in contents])
    else:
        ignored_names = set()

    destination.mkdir(parents=True, exist_ok=True)

    for subpath in contents:
        if subpath.name in ignored_names:
            continue
        if subpath.is_file():
            subpath.copy(
                destination / subpath.name, force_overwrite_to_cloud=force_overwrite_to_cloud
            )
        elif subpath.is_dir():
            subpath.copytree(
                destination / (subpath.name + ("" if subpath.name.endswith("/") else "/")),
                force_overwrite_to_cloud=force_overwrite_to_cloud,
                ignore=ignore,
            )

    return destination
download_to(destination: Union[str, os.PathLike]) -> Path
Source code in cloudpathlib/cloudpath.py 
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
def download_to(self, destination: Union[str, os.PathLike]) -> Path:
    destination = Path(destination)

    if not self.exists():
        raise CloudPathNotExistsError(f"Cannot download because path does not exist: {self}")

    if self.is_file():
        if destination.is_dir():
            destination = destination / self.name
        return 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)

        return destination
exists(follow_symlinks=True) -> bool
Source code in cloudpathlib/cloudpath.py 
447
448
def exists(self, follow_symlinks=True) -> bool:
    return self.client._exists(self)
from_uri(uri: str) -> Self classmethod
Source code in cloudpathlib/cloudpath.py 
460
461
462
@classmethod
def from_uri(cls, uri: str) -> Self:
    return cls(uri)
full_match(pattern: str, case_sensitive: Optional[bool] = None) -> bool
Source code in cloudpathlib/cloudpath.py 
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
def full_match(self, pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    if sys.version_info < (3, 13):
        raise NotImplementedError("full_match requires Python 3.13 or higher")

    # strip scheme from start of pattern before testing
    if pattern.startswith(self.anchor + self.drive):
        pattern = pattern[len(self.anchor + self.drive) :]
    elif pattern.startswith(self.anchor):
        # for http paths, keep leading slash
        pattern = pattern[len(self.anchor) - 1 :]

    # remove drive, which is kept on normal dispatch to pathlib
    return PurePosixPath(self._no_prefix_no_drive).full_match(  # type: ignore[attr-defined]
        pattern, case_sensitive=case_sensitive
    )
glob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]
Source code in cloudpathlib/cloudpath.py 
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
def glob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(
        selector,
        "/" in pattern
        or "**"
        in pattern,  # recursive listing needed if explicit ** or any sub folder in pattern
    )
info() -> CloudPathInfo

Return a CloudPathInfo object for this path.

Source code in cloudpathlib/cloudpath.py 
1163
1164
1165
def info(self) -> "CloudPathInfo":
    """Return a CloudPathInfo object for this path."""
    return CloudPathInfo(self)
is_absolute() -> bool
Source code in cloudpathlib/cloudpath.py 
1015
1016
def is_absolute(self) -> bool:
    return True
is_dir(follow_symlinks=True) -> bool
Source code in cloudpathlib/local/localpath.py 
15
16
def is_dir(self, follow_symlinks=True) -> bool:
    return self.client._is_dir(self, follow_symlinks=follow_symlinks)
is_file(follow_symlinks=True) -> bool
Source code in cloudpathlib/local/localpath.py 
18
19
def is_file(self, follow_symlinks=True) -> bool:
    return self.client._is_file(self, follow_symlinks=follow_symlinks)
is_junction()
Source code in cloudpathlib/cloudpath.py 
959
960
def is_junction(self):
    return False  # only windows paths can be junctions, not cloudpaths
is_relative_to(other: Self) -> bool
Source code in cloudpathlib/cloudpath.py 
1038
1039
1040
1041
1042
1043
def is_relative_to(self, other: Self) -> bool:
    try:
        self.relative_to(other)
        return True
    except ValueError:
        return False
is_valid_cloudpath(path: Union[str, CloudPath], raise_on_error: bool = False) -> Union[bool, TypeGuard[Self]] classmethod 
is_valid_cloudpath(
    path: CloudPath, raise_on_error: bool = ...
) -> TypeGuard[Self]

is_valid_cloudpath(
    path: str, raise_on_error: bool = ...
) -> bool
Source code in cloudpathlib/cloudpath.py 
332
333
334
335
336
337
338
339
340
341
342
343
@classmethod
def is_valid_cloudpath(
    cls, path: Union[str, "CloudPath"], raise_on_error: bool = False
) -> Union[bool, TypeGuard[Self]]:
    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() -> Generator[Self, None, None]
Source code in cloudpathlib/cloudpath.py 
579
580
581
582
def iterdir(self) -> Generator[Self, None, None]:
    for f, _ in self.client._list_dir(self, recursive=False):
        if f != self:  # iterdir does not include itself in pathlib
            yield f
joinpath(*pathsegments: Union[str, os.PathLike]) -> Self
Source code in cloudpathlib/cloudpath.py 
1009
1010
def joinpath(self, *pathsegments: Union[str, os.PathLike]) -> Self:
    return self._dispatch_to_path("joinpath", *pathsegments)
match(path_pattern: str, case_sensitive: Optional[bool] = None) -> bool
Source code in cloudpathlib/cloudpath.py 
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
def match(self, path_pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    # 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 + "/") :]

    kwargs = dict(case_sensitive=case_sensitive)

    if sys.version_info < (3, 12):
        kwargs.pop("case_sensitive")

    return self._dispatch_to_path("match", path_pattern, **kwargs)
mkdir(parents=False, exist_ok=False, mode: Optional[Any] = None)
Source code in cloudpathlib/local/implementations/gs.py 
34
35
36
def mkdir(self, parents=False, exist_ok=False, mode: Optional[Any] = None):
    # not possible to make empty directory on gs
    pass
move(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
move(
    target: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move(
    target: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move(
    target: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self to target location, removing the source.

Source code in cloudpathlib/cloudpath.py 
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
def move(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self to target location, removing the source."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )
move_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
move_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self into target directory, preserving the filename and removing the source.

Source code in cloudpathlib/cloudpath.py 
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
def move_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self into target directory, preserving the filename and removing the source."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )
    return cast(Union[Path, Self], result)
open(mode: str = 'r', buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, force_overwrite_from_cloud: Optional[bool] = None, force_overwrite_to_cloud: Optional[bool] = None) -> IO[Any] 
open(
    mode: OpenTextMode = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> TextIOWrapper

open(
    mode: OpenBinaryMode,
    buffering: Literal[0],
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> FileIO

open(
    mode: OpenBinaryModeUpdating,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedRandom

open(
    mode: OpenBinaryModeWriting,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedWriter

open(
    mode: OpenBinaryModeReading,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedReader

open(
    mode: OpenBinaryMode,
    buffering: int = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BinaryIO

open(
    mode: str,
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> IO[Any]
Source code in cloudpathlib/cloudpath.py 
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
def open(
    self,
    mode: str = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
    force_overwrite_to_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
) -> "IO[Any]":
    # if trying to call open on a directory that exists
    exists_on_cloud = self.exists()

    if exists_on_cloud and not self.is_file():
        raise CloudPathIsADirectoryError(
            f"Cannot open directory, only files. Tried to open ({self})"
        )

    if not exists_on_cloud and any(m in mode for m in ("r", "a")):
        raise CloudPathFileNotFoundError(
            f"File opened for read or append, but it does not exist on cloud: {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.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
        wrapped_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_upload(*args, **kwargs) -> None:
            wrapped_close(*args, **kwargs)

            # we should be idempotent and not upload again if
            # we already ran our close method patch
            if not self._dirty:
                return

            # 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)
            self._dirty = False

        buffer.close = _patched_close_upload  # type: ignore

        # 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

    # if we don't want any cache around, remove the cache
    # as soon as the file is closed
    if self.client.file_cache_mode == FileCacheMode.close_file:
        # this may be _patched_close_upload, in which case we need to
        # make sure to call that first so the file gets uploaded
        wrapped_close_for_cache = buffer.close

        def _patched_close_empty_cache(*args, **kwargs):
            wrapped_close_for_cache(*args, **kwargs)

            # remove local file as last step on closing
            self.clear_cache()

        buffer.close = _patched_close_empty_cache  # type: ignore

    return buffer
read_bytes() -> bytes
Source code in cloudpathlib/cloudpath.py 
946
947
948
def read_bytes(self) -> bytes:
    with self.open(mode="rb") as f:
        return f.read()
read_text(encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> str
Source code in cloudpathlib/cloudpath.py 
950
951
952
953
954
955
956
957
def read_text(
    self,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> str:
    with self.open(mode="r", encoding=encoding, errors=errors, newline=newline) as f:
        return f.read()
relative_to(other: Self, walk_up: bool = False) -> PurePosixPath
Source code in cloudpathlib/cloudpath.py 
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
def relative_to(self, other: Self, walk_up: bool = False) -> PurePosixPath:
    # We don't dispatch regularly since this never returns a cloud path (since it is relative, and cloud paths are
    # absolute)
    if not isinstance(other, CloudPath):
        raise ValueError(f"{self} is a cloud path, but {other} is not")
    if self.anchor != other.anchor:
        raise ValueError(
            f"{self} is a {self.anchor} path, but {other} is a {other.anchor} path"
        )

    kwargs = dict(walk_up=walk_up)

    if sys.version_info < (3, 12):
        kwargs.pop("walk_up")

    return self._path.relative_to(other._path, **kwargs)  # type: ignore[call-arg]
rename(target: Self) -> Self
Source code in cloudpathlib/cloudpath.py 
886
887
888
889
def rename(self, target: Self) -> Self:
    # for cloud services replace == rename since we don't just rename,
    # we actually move files
    return self.replace(target)
replace(target: Self) -> Self
Source code in cloudpathlib/cloudpath.py 
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
def replace(self, target: Self) -> Self:
    if type(self) is not type(target):
        raise TypeError(
            f"The target based to rename must be an instantiated class of type: {type(self)}"
        )

    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; rename/replace the files recursively."
        )

    if target == self:
        # Request is to replace/rename this with the same path - nothing to do
        return self

    if target.exists():
        target.unlink()

    self.client._move_file(self, target)
    return target
resolve(strict: bool = False) -> Self
Source code in cloudpathlib/cloudpath.py 
1018
1019
def resolve(self, strict: bool = False) -> Self:
    return self
rglob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]
Source code in cloudpathlib/cloudpath.py 
564
565
566
567
568
569
570
571
572
573
574
575
576
577
def rglob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        ("**",) + tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(selector, True)
rmdir() -> None
Source code in cloudpathlib/cloudpath.py 
891
892
893
894
895
896
897
898
899
900
901
902
903
def rmdir(self) -> None:
    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() -> None

Delete an entire directory tree.

Source code in cloudpathlib/cloudpath.py 
1190
1191
1192
1193
1194
1195
1196
def rmtree(self) -> None:
    """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(other_path: Union[str, os.PathLike]) -> bool
Source code in cloudpathlib/cloudpath.py 
905
906
907
def samefile(self, other_path: Union[str, os.PathLike]) -> bool:
    # all cloud paths are absolute and the paths are used for hash
    return self == other_path
stat(follow_symlinks=True)
Source code in cloudpathlib/local/localpath.py 
21
22
23
24
25
26
27
28
def stat(self, follow_symlinks=True):
    try:
        meta = self.client._stat(self)
    except FileNotFoundError:
        raise NoStatError(
            f"No stats available for {self}; it may be a directory or not exist."
        )
    return meta
touch(exist_ok: bool = True, mode: Optional[Any] = None)
Source code in cloudpathlib/local/localpath.py 
30
31
def touch(self, exist_ok: bool = True, mode: Optional[Any] = None):
    self.client._touch(self, exist_ok)
Source code in cloudpathlib/cloudpath.py 
909
910
911
912
913
914
915
def unlink(self, missing_ok: bool = True) -> None:
    # Note: missing_ok defaults to False in pathlib, but changing the default now would be a breaking change.
    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; call rmdir instead of unlink."
        )
    self.client._remove(self, missing_ok)
upload_from(source: Union[str, os.PathLike], force_overwrite_to_cloud: Optional[bool] = None) -> Self

Upload a file or directory to the cloud path.

Source code in cloudpathlib/cloudpath.py 
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
def upload_from(
    self,
    source: Union[str, os.PathLike],
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self:
    """Upload a file or directory to the cloud path."""
    source = Path(source)

    if source.is_dir():
        for p in source.iterdir():
            (self / p.name).upload_from(p, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return self

    else:
        if self.exists() and self.is_dir():
            dst = self / source.name
        else:
            dst = self

        dst._upload_file_to_cloud(source, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return dst
validate(v: str) -> Self classmethod

Used as a Pydantic validator. See https://docs.pydantic.dev/2.0/usage/types/custom/

Source code in cloudpathlib/cloudpath.py 
1687
1688
1689
1690
1691
@classmethod
def validate(cls, v: str) -> Self:
    """Used as a Pydantic validator. See
    https://docs.pydantic.dev/2.0/usage/types/custom/"""
    return cls(v)
walk(top_down: bool = True, on_error: Optional[Callable] = None, follow_symlinks: bool = False, lazy: bool = False) -> Generator[Tuple[Self, List[str], List[str]], None, None]

Walk the directory tree rooted at this path, similar to :meth:pathlib.Path.walk and :func:os.walk.

By default (lazy=False) the entire subtree is listed up front with a single recursive listing, which is the fastest option for a full walk on cloud backends.

Pass lazy=True to defer listing until each directory is visited (one non-recursive listing per directory). This is slower for a full walk, but lets callers prune dirnames in place (when top_down=True) to avoid fetching the contents of skipped subtrees entirely -- which can be dramatically faster and cheaper for sparse traversals.

follow_symlinks is accepted for signature parity with pathlib but has no effect on cloud backends, which do not have symlinks.

Source code in cloudpathlib/cloudpath.py 
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def walk(
    self,
    top_down: bool = True,
    on_error: Optional[Callable] = None,
    follow_symlinks: bool = False,
    lazy: bool = False,
) -> Generator[Tuple[Self, List[str], List[str]], None, None]:
    """Walk the directory tree rooted at this path, similar to
    :meth:`pathlib.Path.walk` and :func:`os.walk`.

    By default (``lazy=False``) the entire subtree is listed up front with a
    single recursive listing, which is the fastest option for a full walk on
    cloud backends.

    Pass ``lazy=True`` to defer listing until each directory is visited (one
    non-recursive listing per directory). This is slower for a full walk,
    but lets callers prune ``dirnames`` in place (when ``top_down=True``) to
    avoid fetching the contents of skipped subtrees entirely -- which can be
    dramatically faster and cheaper for sparse traversals.

    ``follow_symlinks`` is accepted for signature parity with ``pathlib``
    but has no effect on cloud backends, which do not have symlinks.
    """
    if lazy:
        yield from self._walk_lazy(top_down=top_down, on_error=on_error)
        return

    try:
        file_tree = self._build_subtree(recursive=True)  # walking is always recursive
        yield from self._walk_results_from_tree(self, file_tree, top_down=top_down)

    except Exception as e:
        if on_error is not None:
            on_error(e)
        else:
            raise
with_name(name: str) -> Self
Source code in cloudpathlib/cloudpath.py 
1119
1120
def with_name(self, name: str) -> Self:
    return self._dispatch_to_path("with_name", name)
with_segments(*pathsegments) -> Self

Create a new CloudPath with the same client out of the given segments. The first segment will be interpreted as the bucket/container name.

Source code in cloudpathlib/cloudpath.py 
1122
1123
1124
1125
1126
def with_segments(self, *pathsegments) -> Self:
    """Create a new CloudPath with the same client out of the given segments.
    The first segment will be interpreted as the bucket/container name.
    """
    return self._new_cloudpath("/".join(pathsegments))
with_stem(stem: str) -> Self
Source code in cloudpathlib/cloudpath.py 
1112
1113
1114
1115
1116
1117
def with_stem(self, stem: str) -> Self:
    try:
        return self._dispatch_to_path("with_stem", stem)
    except AttributeError:
        # with_stem was only added in python 3.9, so we fallback for compatibility
        return self.with_name(stem + self.suffix)
with_suffix(suffix: str) -> Self
Source code in cloudpathlib/cloudpath.py 
1128
1129
def with_suffix(self, suffix: str) -> Self:
    return self._dispatch_to_path("with_suffix", suffix)
write_bytes(data: bytes) -> int

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

Source code in cloudpathlib/cloudpath.py 
917
918
919
920
921
922
923
924
925
926
def write_bytes(self, data: bytes) -> int:
    """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(data: str, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> int

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.10/Lib/pathlib.py#L1146-L1155

Source code in cloudpathlib/cloudpath.py 
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
def write_text(
    self,
    data: str,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> int:
    """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.10/Lib/pathlib.py#L1146-L1155
    """
    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, newline=newline) as f:
        return f.write(data)

LocalPath

Bases: CloudPath

Abstract CloudPath for accessing objects the local filesystem. Subclasses are as a monkeypatch substitutes for normal CloudPath subclasses when writing tests.

Source code in cloudpathlib/local/localpath.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
class LocalPath(CloudPath):
    """Abstract CloudPath for accessing objects the local filesystem. Subclasses are as a
    monkeypatch substitutes for normal CloudPath subclasses when writing tests."""

    client: "LocalClient"

    def is_dir(self, follow_symlinks=True) -> bool:
        return self.client._is_dir(self, follow_symlinks=follow_symlinks)

    def is_file(self, follow_symlinks=True) -> bool:
        return self.client._is_file(self, follow_symlinks=follow_symlinks)

    def stat(self, follow_symlinks=True):
        try:
            meta = self.client._stat(self)
        except FileNotFoundError:
            raise NoStatError(
                f"No stats available for {self}; it may be a directory or not exist."
            )
        return meta

    def touch(self, exist_ok: bool = True, mode: Optional[Any] = None):
        self.client._touch(self, exist_ok)

Attributes

anchor: str property
client: LocalClient instance-attribute
cloud_prefix: str instance-attribute
drive: str abstractmethod property

For example "bucket" on S3 or "container" on Azure; needs to be defined for each class

fspath: str property
name: str property
parent: Self property
parents: Tuple[Self, ...] property
parser: Self property
parts: Tuple[str, ...] property
stem: str property
suffix: str property
suffixes: List[str] property

Methods:

__init__(cloud_path: Union[str, Self, CloudPath], *parts: str, client: Optional[Client] = None) -> None
Source code in cloudpathlib/cloudpath.py 
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
def __init__(
    self,
    cloud_path: Union[str, Self, "CloudPath"],
    *parts: str,
    client: Optional["Client"] = None,
) -> None:
    # handle if local file gets opened. must be set at the top of the method in case any code
    # below raises an exception, this prevents __del__ from raising an AttributeError
    self._handle: Optional[IO] = None
    self._client: Optional["Client"] = None

    if parts:
        # ensure first part ends in "/"; (sometimes it is just prefix, sometimes a longer path)
        if not str(cloud_path).endswith("/"):
            cloud_path = str(cloud_path) + "/"

        cloud_path = str(cloud_path) + "/".join(p.strip("/") for p in parts)

    self.is_valid_cloudpath(cloud_path, raise_on_error=True)
    self._cloud_meta.validate_completeness()

    # 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):
            self._client = cloud_path.client
    else:
        self._client = client

    if client is not None and 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."
        )

    # track if local has been written to, if so it may need to be uploaded
    self._dirty = False
absolute() -> Self
Source code in cloudpathlib/cloudpath.py 
1012
1013
def absolute(self) -> Self:
    return self
as_uri() -> str
Source code in cloudpathlib/cloudpath.py 
444
445
def as_uri(self) -> str:
    return str(self)
as_url(presign: bool = False, expire_seconds: int = 60 * 60) -> str
Source code in cloudpathlib/cloudpath.py 
426
427
428
429
430
431
def as_url(self, presign: bool = False, expire_seconds: int = 60 * 60) -> str:
    if presign:
        url = self.client._generate_presigned_url(self, expire_seconds=expire_seconds)
    else:
        url = self.client._get_public_url(self)
    return url
clear_cache()

Removes cache if it exists

Source code in cloudpathlib/cloudpath.py 
1525
1526
1527
1528
1529
1530
1531
def clear_cache(self):
    """Removes cache if it exists"""
    if self._local.exists():
        if self._local.is_file():
            self._local.unlink()
        else:
            shutil.rmtree(self._local)
copy(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
copy(
    target: Self,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy(
    target: Path,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy(
    target: str,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self to target folder or file, if self is a file.

Source code in cloudpathlib/cloudpath.py 
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
def copy(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self to target folder or file, if self is a file."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )
copy_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
copy_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self into target directory, preserving the filename.

Source code in cloudpathlib/cloudpath.py 
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
def copy_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self into target directory, preserving the filename."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )
    return cast(Union[Path, Self], result)
copytree(destination, force_overwrite_to_cloud=None, ignore=None) 
copytree(
    destination: Self,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Self

copytree(
    destination: Path,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Path

copytree(
    destination: Union[str, os.PathLike, Self],
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Union[Path, CloudPath]

Copy self to a directory, if self is a directory.

Source code in cloudpathlib/cloudpath.py 
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
def copytree(self, destination, force_overwrite_to_cloud=None, ignore=None):
    """Copy self to a directory, if self is a directory."""
    if not self.is_dir():
        raise CloudPathNotADirectoryError(
            f"Origin path {self} must be a directory. To copy a single file use the method copy."
        )

    destination = anypath.to_anypath(destination)

    if destination.exists() and destination.is_file():
        raise CloudPathFileExistsError(
            f"Destination path {destination} of copytree must be a directory."
        )

    contents = list(self.iterdir())

    if ignore is not None:
        ignored_names = ignore(self._no_prefix_no_drive, [x.name for x in contents])
    else:
        ignored_names = set()

    destination.mkdir(parents=True, exist_ok=True)

    for subpath in contents:
        if subpath.name in ignored_names:
            continue
        if subpath.is_file():
            subpath.copy(
                destination / subpath.name, force_overwrite_to_cloud=force_overwrite_to_cloud
            )
        elif subpath.is_dir():
            subpath.copytree(
                destination / (subpath.name + ("" if subpath.name.endswith("/") else "/")),
                force_overwrite_to_cloud=force_overwrite_to_cloud,
                ignore=ignore,
            )

    return destination
download_to(destination: Union[str, os.PathLike]) -> Path
Source code in cloudpathlib/cloudpath.py 
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
def download_to(self, destination: Union[str, os.PathLike]) -> Path:
    destination = Path(destination)

    if not self.exists():
        raise CloudPathNotExistsError(f"Cannot download because path does not exist: {self}")

    if self.is_file():
        if destination.is_dir():
            destination = destination / self.name
        return 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)

        return destination
exists(follow_symlinks=True) -> bool
Source code in cloudpathlib/cloudpath.py 
447
448
def exists(self, follow_symlinks=True) -> bool:
    return self.client._exists(self)
from_uri(uri: str) -> Self classmethod
Source code in cloudpathlib/cloudpath.py 
460
461
462
@classmethod
def from_uri(cls, uri: str) -> Self:
    return cls(uri)
full_match(pattern: str, case_sensitive: Optional[bool] = None) -> bool
Source code in cloudpathlib/cloudpath.py 
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
def full_match(self, pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    if sys.version_info < (3, 13):
        raise NotImplementedError("full_match requires Python 3.13 or higher")

    # strip scheme from start of pattern before testing
    if pattern.startswith(self.anchor + self.drive):
        pattern = pattern[len(self.anchor + self.drive) :]
    elif pattern.startswith(self.anchor):
        # for http paths, keep leading slash
        pattern = pattern[len(self.anchor) - 1 :]

    # remove drive, which is kept on normal dispatch to pathlib
    return PurePosixPath(self._no_prefix_no_drive).full_match(  # type: ignore[attr-defined]
        pattern, case_sensitive=case_sensitive
    )
glob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]
Source code in cloudpathlib/cloudpath.py 
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
def glob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(
        selector,
        "/" in pattern
        or "**"
        in pattern,  # recursive listing needed if explicit ** or any sub folder in pattern
    )
info() -> CloudPathInfo

Return a CloudPathInfo object for this path.

Source code in cloudpathlib/cloudpath.py 
1163
1164
1165
def info(self) -> "CloudPathInfo":
    """Return a CloudPathInfo object for this path."""
    return CloudPathInfo(self)
is_absolute() -> bool
Source code in cloudpathlib/cloudpath.py 
1015
1016
def is_absolute(self) -> bool:
    return True
is_dir(follow_symlinks=True) -> bool
Source code in cloudpathlib/local/localpath.py 
15
16
def is_dir(self, follow_symlinks=True) -> bool:
    return self.client._is_dir(self, follow_symlinks=follow_symlinks)
is_file(follow_symlinks=True) -> bool
Source code in cloudpathlib/local/localpath.py 
18
19
def is_file(self, follow_symlinks=True) -> bool:
    return self.client._is_file(self, follow_symlinks=follow_symlinks)
is_junction()
Source code in cloudpathlib/cloudpath.py 
959
960
def is_junction(self):
    return False  # only windows paths can be junctions, not cloudpaths
is_relative_to(other: Self) -> bool
Source code in cloudpathlib/cloudpath.py 
1038
1039
1040
1041
1042
1043
def is_relative_to(self, other: Self) -> bool:
    try:
        self.relative_to(other)
        return True
    except ValueError:
        return False
is_valid_cloudpath(path: Union[str, CloudPath], raise_on_error: bool = False) -> Union[bool, TypeGuard[Self]] classmethod 
is_valid_cloudpath(
    path: CloudPath, raise_on_error: bool = ...
) -> TypeGuard[Self]

is_valid_cloudpath(
    path: str, raise_on_error: bool = ...
) -> bool
Source code in cloudpathlib/cloudpath.py 
332
333
334
335
336
337
338
339
340
341
342
343
@classmethod
def is_valid_cloudpath(
    cls, path: Union[str, "CloudPath"], raise_on_error: bool = False
) -> Union[bool, TypeGuard[Self]]:
    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() -> Generator[Self, None, None]
Source code in cloudpathlib/cloudpath.py 
579
580
581
582
def iterdir(self) -> Generator[Self, None, None]:
    for f, _ in self.client._list_dir(self, recursive=False):
        if f != self:  # iterdir does not include itself in pathlib
            yield f
joinpath(*pathsegments: Union[str, os.PathLike]) -> Self
Source code in cloudpathlib/cloudpath.py 
1009
1010
def joinpath(self, *pathsegments: Union[str, os.PathLike]) -> Self:
    return self._dispatch_to_path("joinpath", *pathsegments)
match(path_pattern: str, case_sensitive: Optional[bool] = None) -> bool
Source code in cloudpathlib/cloudpath.py 
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
def match(self, path_pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    # 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 + "/") :]

    kwargs = dict(case_sensitive=case_sensitive)

    if sys.version_info < (3, 12):
        kwargs.pop("case_sensitive")

    return self._dispatch_to_path("match", path_pattern, **kwargs)
mkdir(parents: bool = False, exist_ok: bool = False, mode: Optional[Any] = None) -> None abstractmethod

Should be implemented using the client API without requiring a dir is downloaded

Source code in cloudpathlib/cloudpath.py 
414
415
416
417
418
419
@abc.abstractmethod
def mkdir(
    self, parents: bool = False, exist_ok: bool = False, mode: Optional[Any] = None
) -> None:
    """Should be implemented using the client API without requiring a dir is downloaded"""
    pass
move(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
move(
    target: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move(
    target: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move(
    target: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self to target location, removing the source.

Source code in cloudpathlib/cloudpath.py 
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
def move(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self to target location, removing the source."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )
move_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
move_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self into target directory, preserving the filename and removing the source.

Source code in cloudpathlib/cloudpath.py 
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
def move_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self into target directory, preserving the filename and removing the source."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )
    return cast(Union[Path, Self], result)
open(mode: str = 'r', buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, force_overwrite_from_cloud: Optional[bool] = None, force_overwrite_to_cloud: Optional[bool] = None) -> IO[Any] 
open(
    mode: OpenTextMode = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> TextIOWrapper

open(
    mode: OpenBinaryMode,
    buffering: Literal[0],
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> FileIO

open(
    mode: OpenBinaryModeUpdating,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedRandom

open(
    mode: OpenBinaryModeWriting,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedWriter

open(
    mode: OpenBinaryModeReading,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedReader

open(
    mode: OpenBinaryMode,
    buffering: int = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BinaryIO

open(
    mode: str,
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> IO[Any]
Source code in cloudpathlib/cloudpath.py 
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
def open(
    self,
    mode: str = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
    force_overwrite_to_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
) -> "IO[Any]":
    # if trying to call open on a directory that exists
    exists_on_cloud = self.exists()

    if exists_on_cloud and not self.is_file():
        raise CloudPathIsADirectoryError(
            f"Cannot open directory, only files. Tried to open ({self})"
        )

    if not exists_on_cloud and any(m in mode for m in ("r", "a")):
        raise CloudPathFileNotFoundError(
            f"File opened for read or append, but it does not exist on cloud: {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.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
        wrapped_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_upload(*args, **kwargs) -> None:
            wrapped_close(*args, **kwargs)

            # we should be idempotent and not upload again if
            # we already ran our close method patch
            if not self._dirty:
                return

            # 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)
            self._dirty = False

        buffer.close = _patched_close_upload  # type: ignore

        # 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

    # if we don't want any cache around, remove the cache
    # as soon as the file is closed
    if self.client.file_cache_mode == FileCacheMode.close_file:
        # this may be _patched_close_upload, in which case we need to
        # make sure to call that first so the file gets uploaded
        wrapped_close_for_cache = buffer.close

        def _patched_close_empty_cache(*args, **kwargs):
            wrapped_close_for_cache(*args, **kwargs)

            # remove local file as last step on closing
            self.clear_cache()

        buffer.close = _patched_close_empty_cache  # type: ignore

    return buffer
read_bytes() -> bytes
Source code in cloudpathlib/cloudpath.py 
946
947
948
def read_bytes(self) -> bytes:
    with self.open(mode="rb") as f:
        return f.read()
read_text(encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> str
Source code in cloudpathlib/cloudpath.py 
950
951
952
953
954
955
956
957
def read_text(
    self,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> str:
    with self.open(mode="r", encoding=encoding, errors=errors, newline=newline) as f:
        return f.read()
relative_to(other: Self, walk_up: bool = False) -> PurePosixPath
Source code in cloudpathlib/cloudpath.py 
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
def relative_to(self, other: Self, walk_up: bool = False) -> PurePosixPath:
    # We don't dispatch regularly since this never returns a cloud path (since it is relative, and cloud paths are
    # absolute)
    if not isinstance(other, CloudPath):
        raise ValueError(f"{self} is a cloud path, but {other} is not")
    if self.anchor != other.anchor:
        raise ValueError(
            f"{self} is a {self.anchor} path, but {other} is a {other.anchor} path"
        )

    kwargs = dict(walk_up=walk_up)

    if sys.version_info < (3, 12):
        kwargs.pop("walk_up")

    return self._path.relative_to(other._path, **kwargs)  # type: ignore[call-arg]
rename(target: Self) -> Self
Source code in cloudpathlib/cloudpath.py 
886
887
888
889
def rename(self, target: Self) -> Self:
    # for cloud services replace == rename since we don't just rename,
    # we actually move files
    return self.replace(target)
replace(target: Self) -> Self
Source code in cloudpathlib/cloudpath.py 
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
def replace(self, target: Self) -> Self:
    if type(self) is not type(target):
        raise TypeError(
            f"The target based to rename must be an instantiated class of type: {type(self)}"
        )

    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; rename/replace the files recursively."
        )

    if target == self:
        # Request is to replace/rename this with the same path - nothing to do
        return self

    if target.exists():
        target.unlink()

    self.client._move_file(self, target)
    return target
resolve(strict: bool = False) -> Self
Source code in cloudpathlib/cloudpath.py 
1018
1019
def resolve(self, strict: bool = False) -> Self:
    return self
rglob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]
Source code in cloudpathlib/cloudpath.py 
564
565
566
567
568
569
570
571
572
573
574
575
576
577
def rglob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        ("**",) + tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(selector, True)
rmdir() -> None
Source code in cloudpathlib/cloudpath.py 
891
892
893
894
895
896
897
898
899
900
901
902
903
def rmdir(self) -> None:
    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() -> None

Delete an entire directory tree.

Source code in cloudpathlib/cloudpath.py 
1190
1191
1192
1193
1194
1195
1196
def rmtree(self) -> None:
    """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(other_path: Union[str, os.PathLike]) -> bool
Source code in cloudpathlib/cloudpath.py 
905
906
907
def samefile(self, other_path: Union[str, os.PathLike]) -> bool:
    # all cloud paths are absolute and the paths are used for hash
    return self == other_path
stat(follow_symlinks=True)
Source code in cloudpathlib/local/localpath.py 
21
22
23
24
25
26
27
28
def stat(self, follow_symlinks=True):
    try:
        meta = self.client._stat(self)
    except FileNotFoundError:
        raise NoStatError(
            f"No stats available for {self}; it may be a directory or not exist."
        )
    return meta
touch(exist_ok: bool = True, mode: Optional[Any] = None)
Source code in cloudpathlib/local/localpath.py 
30
31
def touch(self, exist_ok: bool = True, mode: Optional[Any] = None):
    self.client._touch(self, exist_ok)
Source code in cloudpathlib/cloudpath.py 
909
910
911
912
913
914
915
def unlink(self, missing_ok: bool = True) -> None:
    # Note: missing_ok defaults to False in pathlib, but changing the default now would be a breaking change.
    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; call rmdir instead of unlink."
        )
    self.client._remove(self, missing_ok)
upload_from(source: Union[str, os.PathLike], force_overwrite_to_cloud: Optional[bool] = None) -> Self

Upload a file or directory to the cloud path.

Source code in cloudpathlib/cloudpath.py 
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
def upload_from(
    self,
    source: Union[str, os.PathLike],
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self:
    """Upload a file or directory to the cloud path."""
    source = Path(source)

    if source.is_dir():
        for p in source.iterdir():
            (self / p.name).upload_from(p, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return self

    else:
        if self.exists() and self.is_dir():
            dst = self / source.name
        else:
            dst = self

        dst._upload_file_to_cloud(source, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return dst
validate(v: str) -> Self classmethod

Used as a Pydantic validator. See https://docs.pydantic.dev/2.0/usage/types/custom/

Source code in cloudpathlib/cloudpath.py 
1687
1688
1689
1690
1691
@classmethod
def validate(cls, v: str) -> Self:
    """Used as a Pydantic validator. See
    https://docs.pydantic.dev/2.0/usage/types/custom/"""
    return cls(v)
walk(top_down: bool = True, on_error: Optional[Callable] = None, follow_symlinks: bool = False, lazy: bool = False) -> Generator[Tuple[Self, List[str], List[str]], None, None]

Walk the directory tree rooted at this path, similar to :meth:pathlib.Path.walk and :func:os.walk.

By default (lazy=False) the entire subtree is listed up front with a single recursive listing, which is the fastest option for a full walk on cloud backends.

Pass lazy=True to defer listing until each directory is visited (one non-recursive listing per directory). This is slower for a full walk, but lets callers prune dirnames in place (when top_down=True) to avoid fetching the contents of skipped subtrees entirely -- which can be dramatically faster and cheaper for sparse traversals.

follow_symlinks is accepted for signature parity with pathlib but has no effect on cloud backends, which do not have symlinks.

Source code in cloudpathlib/cloudpath.py 
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def walk(
    self,
    top_down: bool = True,
    on_error: Optional[Callable] = None,
    follow_symlinks: bool = False,
    lazy: bool = False,
) -> Generator[Tuple[Self, List[str], List[str]], None, None]:
    """Walk the directory tree rooted at this path, similar to
    :meth:`pathlib.Path.walk` and :func:`os.walk`.

    By default (``lazy=False``) the entire subtree is listed up front with a
    single recursive listing, which is the fastest option for a full walk on
    cloud backends.

    Pass ``lazy=True`` to defer listing until each directory is visited (one
    non-recursive listing per directory). This is slower for a full walk,
    but lets callers prune ``dirnames`` in place (when ``top_down=True``) to
    avoid fetching the contents of skipped subtrees entirely -- which can be
    dramatically faster and cheaper for sparse traversals.

    ``follow_symlinks`` is accepted for signature parity with ``pathlib``
    but has no effect on cloud backends, which do not have symlinks.
    """
    if lazy:
        yield from self._walk_lazy(top_down=top_down, on_error=on_error)
        return

    try:
        file_tree = self._build_subtree(recursive=True)  # walking is always recursive
        yield from self._walk_results_from_tree(self, file_tree, top_down=top_down)

    except Exception as e:
        if on_error is not None:
            on_error(e)
        else:
            raise
with_name(name: str) -> Self
Source code in cloudpathlib/cloudpath.py 
1119
1120
def with_name(self, name: str) -> Self:
    return self._dispatch_to_path("with_name", name)
with_segments(*pathsegments) -> Self

Create a new CloudPath with the same client out of the given segments. The first segment will be interpreted as the bucket/container name.

Source code in cloudpathlib/cloudpath.py 
1122
1123
1124
1125
1126
def with_segments(self, *pathsegments) -> Self:
    """Create a new CloudPath with the same client out of the given segments.
    The first segment will be interpreted as the bucket/container name.
    """
    return self._new_cloudpath("/".join(pathsegments))
with_stem(stem: str) -> Self
Source code in cloudpathlib/cloudpath.py 
1112
1113
1114
1115
1116
1117
def with_stem(self, stem: str) -> Self:
    try:
        return self._dispatch_to_path("with_stem", stem)
    except AttributeError:
        # with_stem was only added in python 3.9, so we fallback for compatibility
        return self.with_name(stem + self.suffix)
with_suffix(suffix: str) -> Self
Source code in cloudpathlib/cloudpath.py 
1128
1129
def with_suffix(self, suffix: str) -> Self:
    return self._dispatch_to_path("with_suffix", suffix)
write_bytes(data: bytes) -> int

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

Source code in cloudpathlib/cloudpath.py 
917
918
919
920
921
922
923
924
925
926
def write_bytes(self, data: bytes) -> int:
    """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(data: str, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> int

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.10/Lib/pathlib.py#L1146-L1155

Source code in cloudpathlib/cloudpath.py 
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
def write_text(
    self,
    data: str,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> int:
    """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.10/Lib/pathlib.py#L1146-L1155
    """
    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, newline=newline) as f:
        return f.write(data)

LocalS3Client

Bases: LocalClient

Replacement for S3Client that uses the local file system. Intended as a monkeypatch substitute when writing tests.

Source code in cloudpathlib/local/implementations/s3.py 
11
12
13
14
15
16
class LocalS3Client(LocalClient):
    """Replacement for S3Client that uses the local file system. Intended as a monkeypatch
    substitute when writing tests.
    """

    _cloud_meta = local_s3_implementation

Attributes

content_type_method = content_type_method instance-attribute
file_cache_mode = file_cache_mode instance-attribute
local_storage_dir: Path property

The local directory where files are stored for this client. This storage directory is the one that simulates the cloud. If no storage directory was provided on instantiating the client, the default storage directory for this client class is used.

Methods:

CloudPath(cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath
Source code in cloudpathlib/client.py 
111
112
def CloudPath(self, cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath:
    return self._cloud_meta.path_class(cloud_path, *parts, client=self)  # type: ignore
__init__(*args, local_storage_dir: Optional[Union[str, os.PathLike]] = None, file_cache_mode: Optional[Union[str, FileCacheMode]] = None, local_cache_dir: Optional[Union[str, os.PathLike]] = None, content_type_method: Optional[Callable] = mimetypes.guess_type, **kwargs)
Source code in cloudpathlib/local/localclient.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def __init__(
    self,
    *args,
    local_storage_dir: Optional[Union[str, os.PathLike]] = None,
    file_cache_mode: Optional[Union[str, FileCacheMode]] = None,
    local_cache_dir: Optional[Union[str, os.PathLike]] = None,
    content_type_method: Optional[Callable] = mimetypes.guess_type,
    **kwargs,
):
    self._local_storage_dir = local_storage_dir

    super().__init__(
        local_cache_dir=local_cache_dir,
        content_type_method=content_type_method,
        file_cache_mode=file_cache_mode,
    )
clear_cache()

Clears the contents of the cache folder. Does not remove folder so it can keep being written to.

Source code in cloudpathlib/client.py 
114
115
116
117
118
119
120
121
122
123
def clear_cache(self):
    """Clears the contents of the cache folder.
    Does not remove folder so it can keep being written to.
    """
    if self._local_cache_dir.exists():
        for p in self._local_cache_dir.iterdir():
            if p.is_file():
                p.unlink()
            else:
                shutil.rmtree(p)
get_default_client() -> Client[BoundedCloudPath] classmethod

Get the default client, which the one that is used when instantiating a cloud path instance for this cloud without a client specified.

Source code in cloudpathlib/client.py 
 97
 98
 99
100
101
102
103
104
@classmethod
def get_default_client(cls) -> "Client[BoundedCloudPath]":
    """Get the default client, which the one that is used when instantiating a cloud path
    instance for this cloud without a client specified.
    """
    if cls._default_client is None:
        cls._default_client = cls()
    return cls._default_client
get_default_storage_dir() -> Path classmethod

Return the default storage directory for this client class. This is used if a client is instantiated without a storage directory being explicitly provided. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
46
47
48
49
50
51
52
53
54
55
@classmethod
def get_default_storage_dir(cls) -> Path:
    """Return the default storage directory for this client class. This is used if a client
    is instantiated without a storage directory being explicitly provided. In this usage,
    "storage" refers to the local storage that simulates the cloud.
    """
    if cls._default_storage_temp_dir is None:
        cls._default_storage_temp_dir = TemporaryDirectory()
        _temp_dirs_to_clean.append(cls._default_storage_temp_dir)
    return Path(cls._default_storage_temp_dir.name)
reset_default_storage_dir() -> Path classmethod

Reset the default storage directly. This tears down and recreates the directory used by default for this client class when instantiating a client without explicitly providing a storage directory. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
57
58
59
60
61
62
63
64
65
@classmethod
def reset_default_storage_dir(cls) -> Path:
    """Reset the default storage directly. This tears down and recreates the directory used by
    default for this client class when instantiating a client without explicitly providing
    a storage directory. In this usage, "storage" refers to the local storage that simulates
    the cloud.
    """
    cls._default_storage_temp_dir = None
    return cls.get_default_storage_dir()
set_as_default_client() -> None

Set this client instance as the default one used when instantiating cloud path instances for this cloud without a client specified.

Source code in cloudpathlib/client.py 
106
107
108
109
def set_as_default_client(self) -> None:
    """Set this client instance as the default one used when instantiating cloud path
    instances for this cloud without a client specified."""
    self.__class__._default_client = self

LocalS3Path

Bases: LocalPath

Replacement for S3Path that uses the local file system. Intended as a monkeypatch substitute when writing tests.

Source code in cloudpathlib/local/implementations/s3.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
class LocalS3Path(LocalPath):
    """Replacement for S3Path that uses the local file system. Intended as a monkeypatch substitute
    when writing tests.
    """

    cloud_prefix: str = "s3://"
    _cloud_meta = local_s3_implementation

    @property
    def drive(self) -> str:
        return self.bucket

    def mkdir(self, parents=False, exist_ok=False, mode: Optional[Any] = None):
        # not possible to make empty directory on s3
        pass

    @property
    def bucket(self) -> str:
        return self._no_prefix.split("/", 1)[0]

    @property
    def key(self) -> str:
        key = self._no_prefix_no_drive

        # key should never have starting slash for
        # use with boto, etc.
        if key.startswith("/"):
            key = key[1:]

        return key

    @property
    def etag(self):
        return self.client._md5(self)

Attributes

anchor: str property
bucket: str property
client: LocalClient instance-attribute
cloud_prefix: str = 's3://' class-attribute instance-attribute
drive: str property
etag property
fspath: str property
key: str property
name: str property
parent: Self property
parents: Tuple[Self, ...] property
parser: Self property
parts: Tuple[str, ...] property
stem: str property
suffix: str property
suffixes: List[str] property

Methods:

__init__(cloud_path: Union[str, Self, CloudPath], *parts: str, client: Optional[Client] = None) -> None
Source code in cloudpathlib/cloudpath.py 
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
def __init__(
    self,
    cloud_path: Union[str, Self, "CloudPath"],
    *parts: str,
    client: Optional["Client"] = None,
) -> None:
    # handle if local file gets opened. must be set at the top of the method in case any code
    # below raises an exception, this prevents __del__ from raising an AttributeError
    self._handle: Optional[IO] = None
    self._client: Optional["Client"] = None

    if parts:
        # ensure first part ends in "/"; (sometimes it is just prefix, sometimes a longer path)
        if not str(cloud_path).endswith("/"):
            cloud_path = str(cloud_path) + "/"

        cloud_path = str(cloud_path) + "/".join(p.strip("/") for p in parts)

    self.is_valid_cloudpath(cloud_path, raise_on_error=True)
    self._cloud_meta.validate_completeness()

    # 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):
            self._client = cloud_path.client
    else:
        self._client = client

    if client is not None and 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."
        )

    # track if local has been written to, if so it may need to be uploaded
    self._dirty = False
absolute() -> Self
Source code in cloudpathlib/cloudpath.py 
1012
1013
def absolute(self) -> Self:
    return self
as_uri() -> str
Source code in cloudpathlib/cloudpath.py 
444
445
def as_uri(self) -> str:
    return str(self)
as_url(presign: bool = False, expire_seconds: int = 60 * 60) -> str
Source code in cloudpathlib/cloudpath.py 
426
427
428
429
430
431
def as_url(self, presign: bool = False, expire_seconds: int = 60 * 60) -> str:
    if presign:
        url = self.client._generate_presigned_url(self, expire_seconds=expire_seconds)
    else:
        url = self.client._get_public_url(self)
    return url
clear_cache()

Removes cache if it exists

Source code in cloudpathlib/cloudpath.py 
1525
1526
1527
1528
1529
1530
1531
def clear_cache(self):
    """Removes cache if it exists"""
    if self._local.exists():
        if self._local.is_file():
            self._local.unlink()
        else:
            shutil.rmtree(self._local)
copy(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
copy(
    target: Self,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy(
    target: Path,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy(
    target: str,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self to target folder or file, if self is a file.

Source code in cloudpathlib/cloudpath.py 
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
def copy(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self to target folder or file, if self is a file."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )
copy_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
copy_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self into target directory, preserving the filename.

Source code in cloudpathlib/cloudpath.py 
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
def copy_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self into target directory, preserving the filename."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )
    return cast(Union[Path, Self], result)
copytree(destination, force_overwrite_to_cloud=None, ignore=None) 
copytree(
    destination: Self,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Self

copytree(
    destination: Path,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Path

copytree(
    destination: Union[str, os.PathLike, Self],
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Union[Path, CloudPath]

Copy self to a directory, if self is a directory.

Source code in cloudpathlib/cloudpath.py 
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
def copytree(self, destination, force_overwrite_to_cloud=None, ignore=None):
    """Copy self to a directory, if self is a directory."""
    if not self.is_dir():
        raise CloudPathNotADirectoryError(
            f"Origin path {self} must be a directory. To copy a single file use the method copy."
        )

    destination = anypath.to_anypath(destination)

    if destination.exists() and destination.is_file():
        raise CloudPathFileExistsError(
            f"Destination path {destination} of copytree must be a directory."
        )

    contents = list(self.iterdir())

    if ignore is not None:
        ignored_names = ignore(self._no_prefix_no_drive, [x.name for x in contents])
    else:
        ignored_names = set()

    destination.mkdir(parents=True, exist_ok=True)

    for subpath in contents:
        if subpath.name in ignored_names:
            continue
        if subpath.is_file():
            subpath.copy(
                destination / subpath.name, force_overwrite_to_cloud=force_overwrite_to_cloud
            )
        elif subpath.is_dir():
            subpath.copytree(
                destination / (subpath.name + ("" if subpath.name.endswith("/") else "/")),
                force_overwrite_to_cloud=force_overwrite_to_cloud,
                ignore=ignore,
            )

    return destination
download_to(destination: Union[str, os.PathLike]) -> Path
Source code in cloudpathlib/cloudpath.py 
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
def download_to(self, destination: Union[str, os.PathLike]) -> Path:
    destination = Path(destination)

    if not self.exists():
        raise CloudPathNotExistsError(f"Cannot download because path does not exist: {self}")

    if self.is_file():
        if destination.is_dir():
            destination = destination / self.name
        return 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)

        return destination
exists(follow_symlinks=True) -> bool
Source code in cloudpathlib/cloudpath.py 
447
448
def exists(self, follow_symlinks=True) -> bool:
    return self.client._exists(self)
from_uri(uri: str) -> Self classmethod
Source code in cloudpathlib/cloudpath.py 
460
461
462
@classmethod
def from_uri(cls, uri: str) -> Self:
    return cls(uri)
full_match(pattern: str, case_sensitive: Optional[bool] = None) -> bool
Source code in cloudpathlib/cloudpath.py 
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
def full_match(self, pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    if sys.version_info < (3, 13):
        raise NotImplementedError("full_match requires Python 3.13 or higher")

    # strip scheme from start of pattern before testing
    if pattern.startswith(self.anchor + self.drive):
        pattern = pattern[len(self.anchor + self.drive) :]
    elif pattern.startswith(self.anchor):
        # for http paths, keep leading slash
        pattern = pattern[len(self.anchor) - 1 :]

    # remove drive, which is kept on normal dispatch to pathlib
    return PurePosixPath(self._no_prefix_no_drive).full_match(  # type: ignore[attr-defined]
        pattern, case_sensitive=case_sensitive
    )
glob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]
Source code in cloudpathlib/cloudpath.py 
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
def glob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(
        selector,
        "/" in pattern
        or "**"
        in pattern,  # recursive listing needed if explicit ** or any sub folder in pattern
    )
info() -> CloudPathInfo

Return a CloudPathInfo object for this path.

Source code in cloudpathlib/cloudpath.py 
1163
1164
1165
def info(self) -> "CloudPathInfo":
    """Return a CloudPathInfo object for this path."""
    return CloudPathInfo(self)
is_absolute() -> bool
Source code in cloudpathlib/cloudpath.py 
1015
1016
def is_absolute(self) -> bool:
    return True
is_dir(follow_symlinks=True) -> bool
Source code in cloudpathlib/local/localpath.py 
15
16
def is_dir(self, follow_symlinks=True) -> bool:
    return self.client._is_dir(self, follow_symlinks=follow_symlinks)
is_file(follow_symlinks=True) -> bool
Source code in cloudpathlib/local/localpath.py 
18
19
def is_file(self, follow_symlinks=True) -> bool:
    return self.client._is_file(self, follow_symlinks=follow_symlinks)
is_junction()
Source code in cloudpathlib/cloudpath.py 
959
960
def is_junction(self):
    return False  # only windows paths can be junctions, not cloudpaths
is_relative_to(other: Self) -> bool
Source code in cloudpathlib/cloudpath.py 
1038
1039
1040
1041
1042
1043
def is_relative_to(self, other: Self) -> bool:
    try:
        self.relative_to(other)
        return True
    except ValueError:
        return False
is_valid_cloudpath(path: Union[str, CloudPath], raise_on_error: bool = False) -> Union[bool, TypeGuard[Self]] classmethod 
is_valid_cloudpath(
    path: CloudPath, raise_on_error: bool = ...
) -> TypeGuard[Self]

is_valid_cloudpath(
    path: str, raise_on_error: bool = ...
) -> bool
Source code in cloudpathlib/cloudpath.py 
332
333
334
335
336
337
338
339
340
341
342
343
@classmethod
def is_valid_cloudpath(
    cls, path: Union[str, "CloudPath"], raise_on_error: bool = False
) -> Union[bool, TypeGuard[Self]]:
    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() -> Generator[Self, None, None]
Source code in cloudpathlib/cloudpath.py 
579
580
581
582
def iterdir(self) -> Generator[Self, None, None]:
    for f, _ in self.client._list_dir(self, recursive=False):
        if f != self:  # iterdir does not include itself in pathlib
            yield f
joinpath(*pathsegments: Union[str, os.PathLike]) -> Self
Source code in cloudpathlib/cloudpath.py 
1009
1010
def joinpath(self, *pathsegments: Union[str, os.PathLike]) -> Self:
    return self._dispatch_to_path("joinpath", *pathsegments)
match(path_pattern: str, case_sensitive: Optional[bool] = None) -> bool
Source code in cloudpathlib/cloudpath.py 
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
def match(self, path_pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    # 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 + "/") :]

    kwargs = dict(case_sensitive=case_sensitive)

    if sys.version_info < (3, 12):
        kwargs.pop("case_sensitive")

    return self._dispatch_to_path("match", path_pattern, **kwargs)
mkdir(parents=False, exist_ok=False, mode: Optional[Any] = None)
Source code in cloudpathlib/local/implementations/s3.py 
34
35
36
def mkdir(self, parents=False, exist_ok=False, mode: Optional[Any] = None):
    # not possible to make empty directory on s3
    pass
move(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
move(
    target: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move(
    target: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move(
    target: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self to target location, removing the source.

Source code in cloudpathlib/cloudpath.py 
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
def move(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self to target location, removing the source."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )
move_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 
move_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self into target directory, preserving the filename and removing the source.

Source code in cloudpathlib/cloudpath.py 
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
def move_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self into target directory, preserving the filename and removing the source."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )
    return cast(Union[Path, Self], result)
open(mode: str = 'r', buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, force_overwrite_from_cloud: Optional[bool] = None, force_overwrite_to_cloud: Optional[bool] = None) -> IO[Any] 
open(
    mode: OpenTextMode = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> TextIOWrapper

open(
    mode: OpenBinaryMode,
    buffering: Literal[0],
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> FileIO

open(
    mode: OpenBinaryModeUpdating,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedRandom

open(
    mode: OpenBinaryModeWriting,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedWriter

open(
    mode: OpenBinaryModeReading,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedReader

open(
    mode: OpenBinaryMode,
    buffering: int = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BinaryIO

open(
    mode: str,
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> IO[Any]
Source code in cloudpathlib/cloudpath.py 
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
def open(
    self,
    mode: str = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
    force_overwrite_to_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
) -> "IO[Any]":
    # if trying to call open on a directory that exists
    exists_on_cloud = self.exists()

    if exists_on_cloud and not self.is_file():
        raise CloudPathIsADirectoryError(
            f"Cannot open directory, only files. Tried to open ({self})"
        )

    if not exists_on_cloud and any(m in mode for m in ("r", "a")):
        raise CloudPathFileNotFoundError(
            f"File opened for read or append, but it does not exist on cloud: {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.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
        wrapped_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_upload(*args, **kwargs) -> None:
            wrapped_close(*args, **kwargs)

            # we should be idempotent and not upload again if
            # we already ran our close method patch
            if not self._dirty:
                return

            # 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)
            self._dirty = False

        buffer.close = _patched_close_upload  # type: ignore

        # 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

    # if we don't want any cache around, remove the cache
    # as soon as the file is closed
    if self.client.file_cache_mode == FileCacheMode.close_file:
        # this may be _patched_close_upload, in which case we need to
        # make sure to call that first so the file gets uploaded
        wrapped_close_for_cache = buffer.close

        def _patched_close_empty_cache(*args, **kwargs):
            wrapped_close_for_cache(*args, **kwargs)

            # remove local file as last step on closing
            self.clear_cache()

        buffer.close = _patched_close_empty_cache  # type: ignore

    return buffer
read_bytes() -> bytes
Source code in cloudpathlib/cloudpath.py 
946
947
948
def read_bytes(self) -> bytes:
    with self.open(mode="rb") as f:
        return f.read()
read_text(encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> str
Source code in cloudpathlib/cloudpath.py 
950
951
952
953
954
955
956
957
def read_text(
    self,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> str:
    with self.open(mode="r", encoding=encoding, errors=errors, newline=newline) as f:
        return f.read()
relative_to(other: Self, walk_up: bool = False) -> PurePosixPath
Source code in cloudpathlib/cloudpath.py 
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
def relative_to(self, other: Self, walk_up: bool = False) -> PurePosixPath:
    # We don't dispatch regularly since this never returns a cloud path (since it is relative, and cloud paths are
    # absolute)
    if not isinstance(other, CloudPath):
        raise ValueError(f"{self} is a cloud path, but {other} is not")
    if self.anchor != other.anchor:
        raise ValueError(
            f"{self} is a {self.anchor} path, but {other} is a {other.anchor} path"
        )

    kwargs = dict(walk_up=walk_up)

    if sys.version_info < (3, 12):
        kwargs.pop("walk_up")

    return self._path.relative_to(other._path, **kwargs)  # type: ignore[call-arg]
rename(target: Self) -> Self
Source code in cloudpathlib/cloudpath.py 
886
887
888
889
def rename(self, target: Self) -> Self:
    # for cloud services replace == rename since we don't just rename,
    # we actually move files
    return self.replace(target)
replace(target: Self) -> Self
Source code in cloudpathlib/cloudpath.py 
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
def replace(self, target: Self) -> Self:
    if type(self) is not type(target):
        raise TypeError(
            f"The target based to rename must be an instantiated class of type: {type(self)}"
        )

    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; rename/replace the files recursively."
        )

    if target == self:
        # Request is to replace/rename this with the same path - nothing to do
        return self

    if target.exists():
        target.unlink()

    self.client._move_file(self, target)
    return target
resolve(strict: bool = False) -> Self
Source code in cloudpathlib/cloudpath.py 
1018
1019
def resolve(self, strict: bool = False) -> Self:
    return self
rglob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]
Source code in cloudpathlib/cloudpath.py 
564
565
566
567
568
569
570
571
572
573
574
575
576
577
def rglob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        ("**",) + tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(selector, True)
rmdir() -> None
Source code in cloudpathlib/cloudpath.py 
891
892
893
894
895
896
897
898
899
900
901
902
903
def rmdir(self) -> None:
    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() -> None

Delete an entire directory tree.

Source code in cloudpathlib/cloudpath.py 
1190
1191
1192
1193
1194
1195
1196
def rmtree(self) -> None:
    """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(other_path: Union[str, os.PathLike]) -> bool
Source code in cloudpathlib/cloudpath.py 
905
906
907
def samefile(self, other_path: Union[str, os.PathLike]) -> bool:
    # all cloud paths are absolute and the paths are used for hash
    return self == other_path
stat(follow_symlinks=True)
Source code in cloudpathlib/local/localpath.py 
21
22
23
24
25
26
27
28
def stat(self, follow_symlinks=True):
    try:
        meta = self.client._stat(self)
    except FileNotFoundError:
        raise NoStatError(
            f"No stats available for {self}; it may be a directory or not exist."
        )
    return meta
touch(exist_ok: bool = True, mode: Optional[Any] = None)
Source code in cloudpathlib/local/localpath.py 
30
31
def touch(self, exist_ok: bool = True, mode: Optional[Any] = None):
    self.client._touch(self, exist_ok)
Source code in cloudpathlib/cloudpath.py 
909
910
911
912
913
914
915
def unlink(self, missing_ok: bool = True) -> None:
    # Note: missing_ok defaults to False in pathlib, but changing the default now would be a breaking change.
    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; call rmdir instead of unlink."
        )
    self.client._remove(self, missing_ok)
upload_from(source: Union[str, os.PathLike], force_overwrite_to_cloud: Optional[bool] = None) -> Self

Upload a file or directory to the cloud path.

Source code in cloudpathlib/cloudpath.py 
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
def upload_from(
    self,
    source: Union[str, os.PathLike],
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self:
    """Upload a file or directory to the cloud path."""
    source = Path(source)

    if source.is_dir():
        for p in source.iterdir():
            (self / p.name).upload_from(p, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return self

    else:
        if self.exists() and self.is_dir():
            dst = self / source.name
        else:
            dst = self

        dst._upload_file_to_cloud(source, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return dst
validate(v: str) -> Self classmethod

Used as a Pydantic validator. See https://docs.pydantic.dev/2.0/usage/types/custom/

Source code in cloudpathlib/cloudpath.py 
1687
1688
1689
1690
1691
@classmethod
def validate(cls, v: str) -> Self:
    """Used as a Pydantic validator. See
    https://docs.pydantic.dev/2.0/usage/types/custom/"""
    return cls(v)
walk(top_down: bool = True, on_error: Optional[Callable] = None, follow_symlinks: bool = False, lazy: bool = False) -> Generator[Tuple[Self, List[str], List[str]], None, None]

Walk the directory tree rooted at this path, similar to :meth:pathlib.Path.walk and :func:os.walk.

By default (lazy=False) the entire subtree is listed up front with a single recursive listing, which is the fastest option for a full walk on cloud backends.

Pass lazy=True to defer listing until each directory is visited (one non-recursive listing per directory). This is slower for a full walk, but lets callers prune dirnames in place (when top_down=True) to avoid fetching the contents of skipped subtrees entirely -- which can be dramatically faster and cheaper for sparse traversals.

follow_symlinks is accepted for signature parity with pathlib but has no effect on cloud backends, which do not have symlinks.

Source code in cloudpathlib/cloudpath.py 
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def walk(
    self,
    top_down: bool = True,
    on_error: Optional[Callable] = None,
    follow_symlinks: bool = False,
    lazy: bool = False,
) -> Generator[Tuple[Self, List[str], List[str]], None, None]:
    """Walk the directory tree rooted at this path, similar to
    :meth:`pathlib.Path.walk` and :func:`os.walk`.

    By default (``lazy=False``) the entire subtree is listed up front with a
    single recursive listing, which is the fastest option for a full walk on
    cloud backends.

    Pass ``lazy=True`` to defer listing until each directory is visited (one
    non-recursive listing per directory). This is slower for a full walk,
    but lets callers prune ``dirnames`` in place (when ``top_down=True``) to
    avoid fetching the contents of skipped subtrees entirely -- which can be
    dramatically faster and cheaper for sparse traversals.

    ``follow_symlinks`` is accepted for signature parity with ``pathlib``
    but has no effect on cloud backends, which do not have symlinks.
    """
    if lazy:
        yield from self._walk_lazy(top_down=top_down, on_error=on_error)
        return

    try:
        file_tree = self._build_subtree(recursive=True)  # walking is always recursive
        yield from self._walk_results_from_tree(self, file_tree, top_down=top_down)

    except Exception as e:
        if on_error is not None:
            on_error(e)
        else:
            raise
with_name(name: str) -> Self
Source code in cloudpathlib/cloudpath.py 
1119
1120
def with_name(self, name: str) -> Self:
    return self._dispatch_to_path("with_name", name)
with_segments(*pathsegments) -> Self

Create a new CloudPath with the same client out of the given segments. The first segment will be interpreted as the bucket/container name.

Source code in cloudpathlib/cloudpath.py 
1122
1123
1124
1125
1126
def with_segments(self, *pathsegments) -> Self:
    """Create a new CloudPath with the same client out of the given segments.
    The first segment will be interpreted as the bucket/container name.
    """
    return self._new_cloudpath("/".join(pathsegments))
with_stem(stem: str) -> Self
Source code in cloudpathlib/cloudpath.py 
1112
1113
1114
1115
1116
1117
def with_stem(self, stem: str) -> Self:
    try:
        return self._dispatch_to_path("with_stem", stem)
    except AttributeError:
        # with_stem was only added in python 3.9, so we fallback for compatibility
        return self.with_name(stem + self.suffix)
with_suffix(suffix: str) -> Self
Source code in cloudpathlib/cloudpath.py 
1128
1129
def with_suffix(self, suffix: str) -> Self:
    return self._dispatch_to_path("with_suffix", suffix)
write_bytes(data: bytes) -> int

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

Source code in cloudpathlib/cloudpath.py 
917
918
919
920
921
922
923
924
925
926
def write_bytes(self, data: bytes) -> int:
    """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(data: str, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> int

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.10/Lib/pathlib.py#L1146-L1155

Source code in cloudpathlib/cloudpath.py 
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
def write_text(
    self,
    data: str,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> int:
    """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.10/Lib/pathlib.py#L1146-L1155
    """
    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, newline=newline) as f:
        return f.write(data)

Attributes

Replacement for "azure" CloudImplementation meta object in cloudpathlib.implementation_registry

Replacement for "gs" CloudImplementation meta object in cloudpathlib.implementation_registry

Replacement for "s3" CloudImplementation meta object in cloudpathlib.implementation_registry

Classes

Bases: LocalClient

Replacement for AzureBlobClient that uses the local file system. Intended as a monkeypatch substitute when writing tests.

Source code in cloudpathlib/local/implementations/azure.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
class LocalAzureBlobClient(LocalClient):
    """Replacement for AzureBlobClient that uses the local file system. Intended as a monkeypatch
    substitute when writing tests.
    """

    _cloud_meta = local_azure_blob_implementation

    def __init__(self, *args, **kwargs):
        cred_opts = [
            kwargs.get("blob_service_client", None),
            kwargs.get("connection_string", None),
            kwargs.get("account_url", None),
            os.getenv("AZURE_STORAGE_CONNECTION_STRING", None),
        ]
        super().__init__(*args, **kwargs)

        if all(opt is None for opt in cred_opts):
            raise MissingCredentialsError(
                "AzureBlobClient does not support anonymous instantiation. "
                "Credentials are required; see docs for options."
            )

Attributes

content_type_method = content_type_method instance-attribute

file_cache_mode = file_cache_mode instance-attribute

local_storage_dir: Path property

The local directory where files are stored for this client. This storage directory is the one that simulates the cloud. If no storage directory was provided on instantiating the client, the default storage directory for this client class is used.

Methods:

CloudPath(cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath

Source code in cloudpathlib/client.py 
111
112
def CloudPath(self, cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath:
    return self._cloud_meta.path_class(cloud_path, *parts, client=self)  # type: ignore

__init__(*args, **kwargs)

Source code in cloudpathlib/local/implementations/azure.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def __init__(self, *args, **kwargs):
    cred_opts = [
        kwargs.get("blob_service_client", None),
        kwargs.get("connection_string", None),
        kwargs.get("account_url", None),
        os.getenv("AZURE_STORAGE_CONNECTION_STRING", None),
    ]
    super().__init__(*args, **kwargs)

    if all(opt is None for opt in cred_opts):
        raise MissingCredentialsError(
            "AzureBlobClient does not support anonymous instantiation. "
            "Credentials are required; see docs for options."
        )

clear_cache()

Clears the contents of the cache folder. Does not remove folder so it can keep being written to.

Source code in cloudpathlib/client.py 
114
115
116
117
118
119
120
121
122
123
def clear_cache(self):
    """Clears the contents of the cache folder.
    Does not remove folder so it can keep being written to.
    """
    if self._local_cache_dir.exists():
        for p in self._local_cache_dir.iterdir():
            if p.is_file():
                p.unlink()
            else:
                shutil.rmtree(p)

get_default_client() -> Client[BoundedCloudPath] classmethod

Get the default client, which the one that is used when instantiating a cloud path instance for this cloud without a client specified.

Source code in cloudpathlib/client.py 
 97
 98
 99
100
101
102
103
104
@classmethod
def get_default_client(cls) -> "Client[BoundedCloudPath]":
    """Get the default client, which the one that is used when instantiating a cloud path
    instance for this cloud without a client specified.
    """
    if cls._default_client is None:
        cls._default_client = cls()
    return cls._default_client

get_default_storage_dir() -> Path classmethod

Return the default storage directory for this client class. This is used if a client is instantiated without a storage directory being explicitly provided. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
46
47
48
49
50
51
52
53
54
55
@classmethod
def get_default_storage_dir(cls) -> Path:
    """Return the default storage directory for this client class. This is used if a client
    is instantiated without a storage directory being explicitly provided. In this usage,
    "storage" refers to the local storage that simulates the cloud.
    """
    if cls._default_storage_temp_dir is None:
        cls._default_storage_temp_dir = TemporaryDirectory()
        _temp_dirs_to_clean.append(cls._default_storage_temp_dir)
    return Path(cls._default_storage_temp_dir.name)

reset_default_storage_dir() -> Path classmethod

Reset the default storage directly. This tears down and recreates the directory used by default for this client class when instantiating a client without explicitly providing a storage directory. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
57
58
59
60
61
62
63
64
65
@classmethod
def reset_default_storage_dir(cls) -> Path:
    """Reset the default storage directly. This tears down and recreates the directory used by
    default for this client class when instantiating a client without explicitly providing
    a storage directory. In this usage, "storage" refers to the local storage that simulates
    the cloud.
    """
    cls._default_storage_temp_dir = None
    return cls.get_default_storage_dir()

set_as_default_client() -> None

Set this client instance as the default one used when instantiating cloud path instances for this cloud without a client specified.

Source code in cloudpathlib/client.py 
106
107
108
109
def set_as_default_client(self) -> None:
    """Set this client instance as the default one used when instantiating cloud path
    instances for this cloud without a client specified."""
    self.__class__._default_client = self

Bases: LocalPath

Replacement for AzureBlobPath that uses the local file system. Intended as a monkeypatch substitute when writing tests.

Source code in cloudpathlib/local/implementations/azure.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
class LocalAzureBlobPath(LocalPath):
    """Replacement for AzureBlobPath that uses the local file system. Intended as a monkeypatch
    substitute when writing tests.
    """

    cloud_prefix: str = "az://"
    _cloud_meta = local_azure_blob_implementation

    @property
    def drive(self) -> str:
        return self.container

    def mkdir(self, parents=False, exist_ok=False, mode: Optional[Any] = None):
        # not possible to make empty directory on blob storage
        pass

    @property
    def container(self) -> str:
        return self._no_prefix.split("/", 1)[0]

    @property
    def blob(self) -> str:
        key = self._no_prefix_no_drive

        # key should never have starting slash for
        if key.startswith("/"):
            key = key[1:]

        return key

    @property
    def etag(self):
        return self.client._md5(self)

    @property
    def md5(self) -> str:
        return self.client._md5(self)

Attributes

anchor: str property

blob: str property

client: LocalClient instance-attribute

cloud_prefix: str = 'az://' class-attribute instance-attribute

container: str property

drive: str property

etag property

fspath: str property

md5: str property

name: str property

parent: Self property

parents: Tuple[Self, ...] property

parser: Self property

parts: Tuple[str, ...] property

stem: str property

suffix: str property

suffixes: List[str] property

Methods:

__init__(cloud_path: Union[str, Self, CloudPath], *parts: str, client: Optional[Client] = None) -> None

Source code in cloudpathlib/cloudpath.py 
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
def __init__(
    self,
    cloud_path: Union[str, Self, "CloudPath"],
    *parts: str,
    client: Optional["Client"] = None,
) -> None:
    # handle if local file gets opened. must be set at the top of the method in case any code
    # below raises an exception, this prevents __del__ from raising an AttributeError
    self._handle: Optional[IO] = None
    self._client: Optional["Client"] = None

    if parts:
        # ensure first part ends in "/"; (sometimes it is just prefix, sometimes a longer path)
        if not str(cloud_path).endswith("/"):
            cloud_path = str(cloud_path) + "/"

        cloud_path = str(cloud_path) + "/".join(p.strip("/") for p in parts)

    self.is_valid_cloudpath(cloud_path, raise_on_error=True)
    self._cloud_meta.validate_completeness()

    # 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):
            self._client = cloud_path.client
    else:
        self._client = client

    if client is not None and 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."
        )

    # track if local has been written to, if so it may need to be uploaded
    self._dirty = False

absolute() -> Self

Source code in cloudpathlib/cloudpath.py 
1012
1013
def absolute(self) -> Self:
    return self

as_uri() -> str

Source code in cloudpathlib/cloudpath.py 
444
445
def as_uri(self) -> str:
    return str(self)

as_url(presign: bool = False, expire_seconds: int = 60 * 60) -> str

Source code in cloudpathlib/cloudpath.py 
426
427
428
429
430
431
def as_url(self, presign: bool = False, expire_seconds: int = 60 * 60) -> str:
    if presign:
        url = self.client._generate_presigned_url(self, expire_seconds=expire_seconds)
    else:
        url = self.client._get_public_url(self)
    return url

clear_cache()

Removes cache if it exists

Source code in cloudpathlib/cloudpath.py 
1525
1526
1527
1528
1529
1530
1531
def clear_cache(self):
    """Removes cache if it exists"""
    if self._local.exists():
        if self._local.is_file():
            self._local.unlink()
        else:
            shutil.rmtree(self._local)

copy(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

copy(
    target: Self,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy(
    target: Path,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy(
    target: str,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self to target folder or file, if self is a file.

Source code in cloudpathlib/cloudpath.py 
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
def copy(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self to target folder or file, if self is a file."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )

copy_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

copy_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self into target directory, preserving the filename.

Source code in cloudpathlib/cloudpath.py 
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
def copy_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self into target directory, preserving the filename."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )
    return cast(Union[Path, Self], result)

copytree(destination, force_overwrite_to_cloud=None, ignore=None) 

copytree(
    destination: Self,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Self

copytree(
    destination: Path,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Path

copytree(
    destination: Union[str, os.PathLike, Self],
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Union[Path, CloudPath]

Copy self to a directory, if self is a directory.

Source code in cloudpathlib/cloudpath.py 
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
def copytree(self, destination, force_overwrite_to_cloud=None, ignore=None):
    """Copy self to a directory, if self is a directory."""
    if not self.is_dir():
        raise CloudPathNotADirectoryError(
            f"Origin path {self} must be a directory. To copy a single file use the method copy."
        )

    destination = anypath.to_anypath(destination)

    if destination.exists() and destination.is_file():
        raise CloudPathFileExistsError(
            f"Destination path {destination} of copytree must be a directory."
        )

    contents = list(self.iterdir())

    if ignore is not None:
        ignored_names = ignore(self._no_prefix_no_drive, [x.name for x in contents])
    else:
        ignored_names = set()

    destination.mkdir(parents=True, exist_ok=True)

    for subpath in contents:
        if subpath.name in ignored_names:
            continue
        if subpath.is_file():
            subpath.copy(
                destination / subpath.name, force_overwrite_to_cloud=force_overwrite_to_cloud
            )
        elif subpath.is_dir():
            subpath.copytree(
                destination / (subpath.name + ("" if subpath.name.endswith("/") else "/")),
                force_overwrite_to_cloud=force_overwrite_to_cloud,
                ignore=ignore,
            )

    return destination

download_to(destination: Union[str, os.PathLike]) -> Path

Source code in cloudpathlib/cloudpath.py 
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
def download_to(self, destination: Union[str, os.PathLike]) -> Path:
    destination = Path(destination)

    if not self.exists():
        raise CloudPathNotExistsError(f"Cannot download because path does not exist: {self}")

    if self.is_file():
        if destination.is_dir():
            destination = destination / self.name
        return 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)

        return destination

exists(follow_symlinks=True) -> bool

Source code in cloudpathlib/cloudpath.py 
447
448
def exists(self, follow_symlinks=True) -> bool:
    return self.client._exists(self)

from_uri(uri: str) -> Self classmethod

Source code in cloudpathlib/cloudpath.py 
460
461
462
@classmethod
def from_uri(cls, uri: str) -> Self:
    return cls(uri)

full_match(pattern: str, case_sensitive: Optional[bool] = None) -> bool

Source code in cloudpathlib/cloudpath.py 
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
def full_match(self, pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    if sys.version_info < (3, 13):
        raise NotImplementedError("full_match requires Python 3.13 or higher")

    # strip scheme from start of pattern before testing
    if pattern.startswith(self.anchor + self.drive):
        pattern = pattern[len(self.anchor + self.drive) :]
    elif pattern.startswith(self.anchor):
        # for http paths, keep leading slash
        pattern = pattern[len(self.anchor) - 1 :]

    # remove drive, which is kept on normal dispatch to pathlib
    return PurePosixPath(self._no_prefix_no_drive).full_match(  # type: ignore[attr-defined]
        pattern, case_sensitive=case_sensitive
    )

glob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]

Source code in cloudpathlib/cloudpath.py 
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
def glob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(
        selector,
        "/" in pattern
        or "**"
        in pattern,  # recursive listing needed if explicit ** or any sub folder in pattern
    )

info() -> CloudPathInfo

Return a CloudPathInfo object for this path.

Source code in cloudpathlib/cloudpath.py 
1163
1164
1165
def info(self) -> "CloudPathInfo":
    """Return a CloudPathInfo object for this path."""
    return CloudPathInfo(self)

is_absolute() -> bool

Source code in cloudpathlib/cloudpath.py 
1015
1016
def is_absolute(self) -> bool:
    return True

is_dir(follow_symlinks=True) -> bool

Source code in cloudpathlib/local/localpath.py 
15
16
def is_dir(self, follow_symlinks=True) -> bool:
    return self.client._is_dir(self, follow_symlinks=follow_symlinks)

is_file(follow_symlinks=True) -> bool

Source code in cloudpathlib/local/localpath.py 
18
19
def is_file(self, follow_symlinks=True) -> bool:
    return self.client._is_file(self, follow_symlinks=follow_symlinks)

is_junction()

Source code in cloudpathlib/cloudpath.py 
959
960
def is_junction(self):
    return False  # only windows paths can be junctions, not cloudpaths

is_relative_to(other: Self) -> bool

Source code in cloudpathlib/cloudpath.py 
1038
1039
1040
1041
1042
1043
def is_relative_to(self, other: Self) -> bool:
    try:
        self.relative_to(other)
        return True
    except ValueError:
        return False

is_valid_cloudpath(path: Union[str, CloudPath], raise_on_error: bool = False) -> Union[bool, TypeGuard[Self]] classmethod 

is_valid_cloudpath(
    path: CloudPath, raise_on_error: bool = ...
) -> TypeGuard[Self]

is_valid_cloudpath(
    path: str, raise_on_error: bool = ...
) -> bool
Source code in cloudpathlib/cloudpath.py 
332
333
334
335
336
337
338
339
340
341
342
343
@classmethod
def is_valid_cloudpath(
    cls, path: Union[str, "CloudPath"], raise_on_error: bool = False
) -> Union[bool, TypeGuard[Self]]:
    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() -> Generator[Self, None, None]

Source code in cloudpathlib/cloudpath.py 
579
580
581
582
def iterdir(self) -> Generator[Self, None, None]:
    for f, _ in self.client._list_dir(self, recursive=False):
        if f != self:  # iterdir does not include itself in pathlib
            yield f

joinpath(*pathsegments: Union[str, os.PathLike]) -> Self

Source code in cloudpathlib/cloudpath.py 
1009
1010
def joinpath(self, *pathsegments: Union[str, os.PathLike]) -> Self:
    return self._dispatch_to_path("joinpath", *pathsegments)

match(path_pattern: str, case_sensitive: Optional[bool] = None) -> bool

Source code in cloudpathlib/cloudpath.py 
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
def match(self, path_pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    # 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 + "/") :]

    kwargs = dict(case_sensitive=case_sensitive)

    if sys.version_info < (3, 12):
        kwargs.pop("case_sensitive")

    return self._dispatch_to_path("match", path_pattern, **kwargs)

mkdir(parents=False, exist_ok=False, mode: Optional[Any] = None)

Source code in cloudpathlib/local/implementations/azure.py 
52
53
54
def mkdir(self, parents=False, exist_ok=False, mode: Optional[Any] = None):
    # not possible to make empty directory on blob storage
    pass

move(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

move(
    target: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move(
    target: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move(
    target: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self to target location, removing the source.

Source code in cloudpathlib/cloudpath.py 
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
def move(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self to target location, removing the source."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )

move_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

move_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self into target directory, preserving the filename and removing the source.

Source code in cloudpathlib/cloudpath.py 
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
def move_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self into target directory, preserving the filename and removing the source."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )
    return cast(Union[Path, Self], result)

open(mode: str = 'r', buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, force_overwrite_from_cloud: Optional[bool] = None, force_overwrite_to_cloud: Optional[bool] = None) -> IO[Any] 

open(
    mode: OpenTextMode = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> TextIOWrapper

open(
    mode: OpenBinaryMode,
    buffering: Literal[0],
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> FileIO

open(
    mode: OpenBinaryModeUpdating,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedRandom

open(
    mode: OpenBinaryModeWriting,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedWriter

open(
    mode: OpenBinaryModeReading,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedReader

open(
    mode: OpenBinaryMode,
    buffering: int = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BinaryIO

open(
    mode: str,
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> IO[Any]
Source code in cloudpathlib/cloudpath.py 
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
def open(
    self,
    mode: str = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
    force_overwrite_to_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
) -> "IO[Any]":
    # if trying to call open on a directory that exists
    exists_on_cloud = self.exists()

    if exists_on_cloud and not self.is_file():
        raise CloudPathIsADirectoryError(
            f"Cannot open directory, only files. Tried to open ({self})"
        )

    if not exists_on_cloud and any(m in mode for m in ("r", "a")):
        raise CloudPathFileNotFoundError(
            f"File opened for read or append, but it does not exist on cloud: {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.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
        wrapped_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_upload(*args, **kwargs) -> None:
            wrapped_close(*args, **kwargs)

            # we should be idempotent and not upload again if
            # we already ran our close method patch
            if not self._dirty:
                return

            # 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)
            self._dirty = False

        buffer.close = _patched_close_upload  # type: ignore

        # 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

    # if we don't want any cache around, remove the cache
    # as soon as the file is closed
    if self.client.file_cache_mode == FileCacheMode.close_file:
        # this may be _patched_close_upload, in which case we need to
        # make sure to call that first so the file gets uploaded
        wrapped_close_for_cache = buffer.close

        def _patched_close_empty_cache(*args, **kwargs):
            wrapped_close_for_cache(*args, **kwargs)

            # remove local file as last step on closing
            self.clear_cache()

        buffer.close = _patched_close_empty_cache  # type: ignore

    return buffer

read_bytes() -> bytes

Source code in cloudpathlib/cloudpath.py 
946
947
948
def read_bytes(self) -> bytes:
    with self.open(mode="rb") as f:
        return f.read()

read_text(encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> str

Source code in cloudpathlib/cloudpath.py 
950
951
952
953
954
955
956
957
def read_text(
    self,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> str:
    with self.open(mode="r", encoding=encoding, errors=errors, newline=newline) as f:
        return f.read()

relative_to(other: Self, walk_up: bool = False) -> PurePosixPath

Source code in cloudpathlib/cloudpath.py 
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
def relative_to(self, other: Self, walk_up: bool = False) -> PurePosixPath:
    # We don't dispatch regularly since this never returns a cloud path (since it is relative, and cloud paths are
    # absolute)
    if not isinstance(other, CloudPath):
        raise ValueError(f"{self} is a cloud path, but {other} is not")
    if self.anchor != other.anchor:
        raise ValueError(
            f"{self} is a {self.anchor} path, but {other} is a {other.anchor} path"
        )

    kwargs = dict(walk_up=walk_up)

    if sys.version_info < (3, 12):
        kwargs.pop("walk_up")

    return self._path.relative_to(other._path, **kwargs)  # type: ignore[call-arg]

rename(target: Self) -> Self

Source code in cloudpathlib/cloudpath.py 
886
887
888
889
def rename(self, target: Self) -> Self:
    # for cloud services replace == rename since we don't just rename,
    # we actually move files
    return self.replace(target)

replace(target: Self) -> Self

Source code in cloudpathlib/cloudpath.py 
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
def replace(self, target: Self) -> Self:
    if type(self) is not type(target):
        raise TypeError(
            f"The target based to rename must be an instantiated class of type: {type(self)}"
        )

    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; rename/replace the files recursively."
        )

    if target == self:
        # Request is to replace/rename this with the same path - nothing to do
        return self

    if target.exists():
        target.unlink()

    self.client._move_file(self, target)
    return target

resolve(strict: bool = False) -> Self

Source code in cloudpathlib/cloudpath.py 
1018
1019
def resolve(self, strict: bool = False) -> Self:
    return self

rglob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]

Source code in cloudpathlib/cloudpath.py 
564
565
566
567
568
569
570
571
572
573
574
575
576
577
def rglob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        ("**",) + tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(selector, True)

rmdir() -> None

Source code in cloudpathlib/cloudpath.py 
891
892
893
894
895
896
897
898
899
900
901
902
903
def rmdir(self) -> None:
    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() -> None

Delete an entire directory tree.

Source code in cloudpathlib/cloudpath.py 
1190
1191
1192
1193
1194
1195
1196
def rmtree(self) -> None:
    """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(other_path: Union[str, os.PathLike]) -> bool

Source code in cloudpathlib/cloudpath.py 
905
906
907
def samefile(self, other_path: Union[str, os.PathLike]) -> bool:
    # all cloud paths are absolute and the paths are used for hash
    return self == other_path

stat(follow_symlinks=True)

Source code in cloudpathlib/local/localpath.py 
21
22
23
24
25
26
27
28
def stat(self, follow_symlinks=True):
    try:
        meta = self.client._stat(self)
    except FileNotFoundError:
        raise NoStatError(
            f"No stats available for {self}; it may be a directory or not exist."
        )
    return meta

touch(exist_ok: bool = True, mode: Optional[Any] = None)

Source code in cloudpathlib/local/localpath.py 
30
31
def touch(self, exist_ok: bool = True, mode: Optional[Any] = None):
    self.client._touch(self, exist_ok)
Source code in cloudpathlib/cloudpath.py 
909
910
911
912
913
914
915
def unlink(self, missing_ok: bool = True) -> None:
    # Note: missing_ok defaults to False in pathlib, but changing the default now would be a breaking change.
    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; call rmdir instead of unlink."
        )
    self.client._remove(self, missing_ok)

upload_from(source: Union[str, os.PathLike], force_overwrite_to_cloud: Optional[bool] = None) -> Self

Upload a file or directory to the cloud path.

Source code in cloudpathlib/cloudpath.py 
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
def upload_from(
    self,
    source: Union[str, os.PathLike],
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self:
    """Upload a file or directory to the cloud path."""
    source = Path(source)

    if source.is_dir():
        for p in source.iterdir():
            (self / p.name).upload_from(p, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return self

    else:
        if self.exists() and self.is_dir():
            dst = self / source.name
        else:
            dst = self

        dst._upload_file_to_cloud(source, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return dst

validate(v: str) -> Self classmethod

Used as a Pydantic validator. See https://docs.pydantic.dev/2.0/usage/types/custom/

Source code in cloudpathlib/cloudpath.py 
1687
1688
1689
1690
1691
@classmethod
def validate(cls, v: str) -> Self:
    """Used as a Pydantic validator. See
    https://docs.pydantic.dev/2.0/usage/types/custom/"""
    return cls(v)

walk(top_down: bool = True, on_error: Optional[Callable] = None, follow_symlinks: bool = False, lazy: bool = False) -> Generator[Tuple[Self, List[str], List[str]], None, None]

Walk the directory tree rooted at this path, similar to :meth:pathlib.Path.walk and :func:os.walk.

By default (lazy=False) the entire subtree is listed up front with a single recursive listing, which is the fastest option for a full walk on cloud backends.

Pass lazy=True to defer listing until each directory is visited (one non-recursive listing per directory). This is slower for a full walk, but lets callers prune dirnames in place (when top_down=True) to avoid fetching the contents of skipped subtrees entirely -- which can be dramatically faster and cheaper for sparse traversals.

follow_symlinks is accepted for signature parity with pathlib but has no effect on cloud backends, which do not have symlinks.

Source code in cloudpathlib/cloudpath.py 
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def walk(
    self,
    top_down: bool = True,
    on_error: Optional[Callable] = None,
    follow_symlinks: bool = False,
    lazy: bool = False,
) -> Generator[Tuple[Self, List[str], List[str]], None, None]:
    """Walk the directory tree rooted at this path, similar to
    :meth:`pathlib.Path.walk` and :func:`os.walk`.

    By default (``lazy=False``) the entire subtree is listed up front with a
    single recursive listing, which is the fastest option for a full walk on
    cloud backends.

    Pass ``lazy=True`` to defer listing until each directory is visited (one
    non-recursive listing per directory). This is slower for a full walk,
    but lets callers prune ``dirnames`` in place (when ``top_down=True``) to
    avoid fetching the contents of skipped subtrees entirely -- which can be
    dramatically faster and cheaper for sparse traversals.

    ``follow_symlinks`` is accepted for signature parity with ``pathlib``
    but has no effect on cloud backends, which do not have symlinks.
    """
    if lazy:
        yield from self._walk_lazy(top_down=top_down, on_error=on_error)
        return

    try:
        file_tree = self._build_subtree(recursive=True)  # walking is always recursive
        yield from self._walk_results_from_tree(self, file_tree, top_down=top_down)

    except Exception as e:
        if on_error is not None:
            on_error(e)
        else:
            raise

with_name(name: str) -> Self

Source code in cloudpathlib/cloudpath.py 
1119
1120
def with_name(self, name: str) -> Self:
    return self._dispatch_to_path("with_name", name)

with_segments(*pathsegments) -> Self

Create a new CloudPath with the same client out of the given segments. The first segment will be interpreted as the bucket/container name.

Source code in cloudpathlib/cloudpath.py 
1122
1123
1124
1125
1126
def with_segments(self, *pathsegments) -> Self:
    """Create a new CloudPath with the same client out of the given segments.
    The first segment will be interpreted as the bucket/container name.
    """
    return self._new_cloudpath("/".join(pathsegments))

with_stem(stem: str) -> Self

Source code in cloudpathlib/cloudpath.py 
1112
1113
1114
1115
1116
1117
def with_stem(self, stem: str) -> Self:
    try:
        return self._dispatch_to_path("with_stem", stem)
    except AttributeError:
        # with_stem was only added in python 3.9, so we fallback for compatibility
        return self.with_name(stem + self.suffix)

with_suffix(suffix: str) -> Self

Source code in cloudpathlib/cloudpath.py 
1128
1129
def with_suffix(self, suffix: str) -> Self:
    return self._dispatch_to_path("with_suffix", suffix)

write_bytes(data: bytes) -> int

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

Source code in cloudpathlib/cloudpath.py 
917
918
919
920
921
922
923
924
925
926
def write_bytes(self, data: bytes) -> int:
    """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(data: str, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> int

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.10/Lib/pathlib.py#L1146-L1155

Source code in cloudpathlib/cloudpath.py 
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
def write_text(
    self,
    data: str,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> int:
    """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.10/Lib/pathlib.py#L1146-L1155
    """
    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, newline=newline) as f:
        return f.write(data)

Bases: Client

Abstract client for accessing objects the local filesystem. Subclasses are as a monkeypatch substitutes for normal Client subclasses when writing tests.

Source code in cloudpathlib/local/localclient.py 
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
class LocalClient(Client):
    """Abstract client for accessing objects the local filesystem. Subclasses are as a monkeypatch
    substitutes for normal Client subclasses when writing tests."""

    # Class-level variable to tracks the default storage directory for this client class
    # that is used if a client is instantiated without a directory being explicitly provided
    _default_storage_temp_dir: ClassVar[Optional[TemporaryDirectory]] = None

    # Instance-level variable that tracks the local storage directory for this client
    _local_storage_dir: Optional[Union[str, os.PathLike]]

    def __init__(
        self,
        *args,
        local_storage_dir: Optional[Union[str, os.PathLike]] = None,
        file_cache_mode: Optional[Union[str, FileCacheMode]] = None,
        local_cache_dir: Optional[Union[str, os.PathLike]] = None,
        content_type_method: Optional[Callable] = mimetypes.guess_type,
        **kwargs,
    ):
        self._local_storage_dir = local_storage_dir

        super().__init__(
            local_cache_dir=local_cache_dir,
            content_type_method=content_type_method,
            file_cache_mode=file_cache_mode,
        )

    @classmethod
    def get_default_storage_dir(cls) -> Path:
        """Return the default storage directory for this client class. This is used if a client
        is instantiated without a storage directory being explicitly provided. In this usage,
        "storage" refers to the local storage that simulates the cloud.
        """
        if cls._default_storage_temp_dir is None:
            cls._default_storage_temp_dir = TemporaryDirectory()
            _temp_dirs_to_clean.append(cls._default_storage_temp_dir)
        return Path(cls._default_storage_temp_dir.name)

    @classmethod
    def reset_default_storage_dir(cls) -> Path:
        """Reset the default storage directly. This tears down and recreates the directory used by
        default for this client class when instantiating a client without explicitly providing
        a storage directory. In this usage, "storage" refers to the local storage that simulates
        the cloud.
        """
        cls._default_storage_temp_dir = None
        return cls.get_default_storage_dir()

    @property
    def local_storage_dir(self) -> Path:
        """The local directory where files are stored for this client. This storage directory is
        the one that simulates the cloud. If no storage directory was provided on instantiating the
        client, the default storage directory for this client class is used.
        """
        if self._local_storage_dir is None:
            # No explicit local storage was provided on instantiating the client.
            # Use the default storage directory for this class.
            return self.get_default_storage_dir()
        return Path(self._local_storage_dir)

    def _cloud_path_to_local(self, cloud_path: "LocalPath") -> Path:
        return self.local_storage_dir / cloud_path._no_prefix

    def _local_to_cloud_path(self, local_path: Union[str, os.PathLike]) -> "LocalPath":
        local_path = Path(local_path)
        cloud_prefix = self._cloud_meta.path_class.cloud_prefix
        return self.CloudPath(
            f"{cloud_prefix}{PurePosixPath(local_path.relative_to(self.local_storage_dir))}"
        )

    def _download_file(self, cloud_path: "LocalPath", local_path: Union[str, os.PathLike]) -> Path:
        local_path = Path(local_path)
        local_path.parent.mkdir(exist_ok=True, parents=True)

        try:
            shutil.copyfile(self._cloud_path_to_local(cloud_path), local_path)
        except FileNotFoundError:
            # erroneous FileNotFoundError appears in tests sometimes; patiently insist on the parent directory existing
            sleep(1.0)
            local_path.parent.mkdir(exist_ok=True, parents=True)
            sleep(1.0)

            shutil.copyfile(self._cloud_path_to_local(cloud_path), local_path)

        return local_path

    def _exists(self, cloud_path: "LocalPath") -> bool:
        return self._cloud_path_to_local(cloud_path).exists()

    def _is_dir(self, cloud_path: "LocalPath", follow_symlinks=True) -> bool:
        kwargs = dict(follow_symlinks=follow_symlinks)
        if sys.version_info < (3, 13):
            kwargs.pop("follow_symlinks")

        return self._cloud_path_to_local(cloud_path).is_dir(**kwargs)

    def _is_file(self, cloud_path: "LocalPath", follow_symlinks=True) -> bool:
        kwargs = dict(follow_symlinks=follow_symlinks)
        if sys.version_info < (3, 13):
            kwargs.pop("follow_symlinks")

        return self._cloud_path_to_local(cloud_path).is_file(**kwargs)

    def _is_file_or_dir(self, cloud_path: "LocalPath") -> Optional[str]:
        if self._is_dir(cloud_path):
            return "dir"
        elif self._is_file(cloud_path):
            return "file"
        else:
            raise FileNotFoundError(f"Path could not be identified as file or dir: {cloud_path}")

    def _list_dir(
        self, cloud_path: "LocalPath", recursive=False
    ) -> Iterable[Tuple["LocalPath", bool]]:
        pattern = "**/*" if recursive else "*"
        for obj in self._cloud_path_to_local(cloud_path).glob(pattern):
            yield (self._local_to_cloud_path(obj), obj.is_dir())

    def _md5(self, cloud_path: "LocalPath") -> str:
        return md5(self._cloud_path_to_local(cloud_path).read_bytes()).hexdigest()

    def _move_file(
        self, src: "LocalPath", dst: "LocalPath", remove_src: bool = True
    ) -> "LocalPath":
        self._cloud_path_to_local(dst).parent.mkdir(exist_ok=True, parents=True)

        if remove_src:
            self._cloud_path_to_local(src).replace(self._cloud_path_to_local(dst))
        else:
            shutil.copy(self._cloud_path_to_local(src), self._cloud_path_to_local(dst))
        return dst

    def _remove(self, cloud_path: "LocalPath", missing_ok: bool = True) -> None:
        local_storage_path = self._cloud_path_to_local(cloud_path)
        if not missing_ok and not local_storage_path.exists():
            raise FileNotFoundError(f"File does not exist: {cloud_path}")

        if local_storage_path.is_file():
            local_storage_path.unlink()
        elif local_storage_path.is_dir():
            shutil.rmtree(local_storage_path)

    def _stat(self, cloud_path: "LocalPath") -> os.stat_result:
        stat_result = self._cloud_path_to_local(cloud_path).stat()

        return os.stat_result(
            (  # type: ignore
                None,  # type: ignore # mode
                None,  # ino
                cloud_path.cloud_prefix,  # dev,
                None,  # nlink,
                None,  # uid,
                None,  # gid,
                stat_result.st_size,  # size,
                None,  # atime,
                stat_result.st_mtime,  # mtime,
                None,  # ctime,
            )
        )

    def _touch(self, cloud_path: "LocalPath", exist_ok: bool = True) -> None:
        local_storage_path = self._cloud_path_to_local(cloud_path)
        if local_storage_path.exists() and not exist_ok:
            raise FileExistsError(f"File exists: {cloud_path}")
        local_storage_path.parent.mkdir(exist_ok=True, parents=True)
        local_storage_path.touch()

    def _upload_file(
        self, local_path: Union[str, os.PathLike], cloud_path: "LocalPath"
    ) -> "LocalPath":
        dst = self._cloud_path_to_local(cloud_path)
        dst.parent.mkdir(exist_ok=True, parents=True)
        shutil.copy(local_path, dst)
        return cloud_path

    def _get_metadata(self, cloud_path: "LocalPath") -> Dict:
        # content_type is the only metadata we test currently
        if self.content_type_method is None:
            content_type_method = lambda x: (None, None)
        else:
            content_type_method = self.content_type_method

        return {
            "content_type": content_type_method(str(self._cloud_path_to_local(cloud_path)))[0],
        }

    def _get_public_url(self, cloud_path: "LocalPath") -> str:
        return cloud_path.as_uri()

    def _generate_presigned_url(
        self, cloud_path: "LocalPath", expire_seconds: int = 60 * 60
    ) -> str:
        public_url = self._get_public_url(cloud_path)
        parts = urlsplit(public_url)
        query = dict(parse_qsl(parts.query, keep_blank_values=True))
        query["expires"] = str(expire_seconds)
        query["signature"] = "local"
        return urlunsplit(parts._replace(query=urlencode(query)))

Attributes

content_type_method = content_type_method instance-attribute

file_cache_mode = file_cache_mode instance-attribute

local_storage_dir: Path property

The local directory where files are stored for this client. This storage directory is the one that simulates the cloud. If no storage directory was provided on instantiating the client, the default storage directory for this client class is used.

Methods:

CloudPath(cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath

Source code in cloudpathlib/client.py 
111
112
def CloudPath(self, cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath:
    return self._cloud_meta.path_class(cloud_path, *parts, client=self)  # type: ignore

__init__(*args, local_storage_dir: Optional[Union[str, os.PathLike]] = None, file_cache_mode: Optional[Union[str, FileCacheMode]] = None, local_cache_dir: Optional[Union[str, os.PathLike]] = None, content_type_method: Optional[Callable] = mimetypes.guess_type, **kwargs)

Source code in cloudpathlib/local/localclient.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def __init__(
    self,
    *args,
    local_storage_dir: Optional[Union[str, os.PathLike]] = None,
    file_cache_mode: Optional[Union[str, FileCacheMode]] = None,
    local_cache_dir: Optional[Union[str, os.PathLike]] = None,
    content_type_method: Optional[Callable] = mimetypes.guess_type,
    **kwargs,
):
    self._local_storage_dir = local_storage_dir

    super().__init__(
        local_cache_dir=local_cache_dir,
        content_type_method=content_type_method,
        file_cache_mode=file_cache_mode,
    )

clear_cache()

Clears the contents of the cache folder. Does not remove folder so it can keep being written to.

Source code in cloudpathlib/client.py 
114
115
116
117
118
119
120
121
122
123
def clear_cache(self):
    """Clears the contents of the cache folder.
    Does not remove folder so it can keep being written to.
    """
    if self._local_cache_dir.exists():
        for p in self._local_cache_dir.iterdir():
            if p.is_file():
                p.unlink()
            else:
                shutil.rmtree(p)

get_default_client() -> Client[BoundedCloudPath] classmethod

Get the default client, which the one that is used when instantiating a cloud path instance for this cloud without a client specified.

Source code in cloudpathlib/client.py 
 97
 98
 99
100
101
102
103
104
@classmethod
def get_default_client(cls) -> "Client[BoundedCloudPath]":
    """Get the default client, which the one that is used when instantiating a cloud path
    instance for this cloud without a client specified.
    """
    if cls._default_client is None:
        cls._default_client = cls()
    return cls._default_client

get_default_storage_dir() -> Path classmethod

Return the default storage directory for this client class. This is used if a client is instantiated without a storage directory being explicitly provided. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
46
47
48
49
50
51
52
53
54
55
@classmethod
def get_default_storage_dir(cls) -> Path:
    """Return the default storage directory for this client class. This is used if a client
    is instantiated without a storage directory being explicitly provided. In this usage,
    "storage" refers to the local storage that simulates the cloud.
    """
    if cls._default_storage_temp_dir is None:
        cls._default_storage_temp_dir = TemporaryDirectory()
        _temp_dirs_to_clean.append(cls._default_storage_temp_dir)
    return Path(cls._default_storage_temp_dir.name)

reset_default_storage_dir() -> Path classmethod

Reset the default storage directly. This tears down and recreates the directory used by default for this client class when instantiating a client without explicitly providing a storage directory. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
57
58
59
60
61
62
63
64
65
@classmethod
def reset_default_storage_dir(cls) -> Path:
    """Reset the default storage directly. This tears down and recreates the directory used by
    default for this client class when instantiating a client without explicitly providing
    a storage directory. In this usage, "storage" refers to the local storage that simulates
    the cloud.
    """
    cls._default_storage_temp_dir = None
    return cls.get_default_storage_dir()

set_as_default_client() -> None

Set this client instance as the default one used when instantiating cloud path instances for this cloud without a client specified.

Source code in cloudpathlib/client.py 
106
107
108
109
def set_as_default_client(self) -> None:
    """Set this client instance as the default one used when instantiating cloud path
    instances for this cloud without a client specified."""
    self.__class__._default_client = self

Bases: LocalClient

Replacement for GSClient that uses the local file system. Intended as a monkeypatch substitute when writing tests.

Source code in cloudpathlib/local/implementations/gs.py 
11
12
13
14
15
16
class LocalGSClient(LocalClient):
    """Replacement for GSClient that uses the local file system. Intended as a monkeypatch
    substitute when writing tests.
    """

    _cloud_meta = local_gs_implementation

Attributes

content_type_method = content_type_method instance-attribute

file_cache_mode = file_cache_mode instance-attribute

local_storage_dir: Path property

The local directory where files are stored for this client. This storage directory is the one that simulates the cloud. If no storage directory was provided on instantiating the client, the default storage directory for this client class is used.

Methods:

CloudPath(cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath

Source code in cloudpathlib/client.py 
111
112
def CloudPath(self, cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath:
    return self._cloud_meta.path_class(cloud_path, *parts, client=self)  # type: ignore

__init__(*args, local_storage_dir: Optional[Union[str, os.PathLike]] = None, file_cache_mode: Optional[Union[str, FileCacheMode]] = None, local_cache_dir: Optional[Union[str, os.PathLike]] = None, content_type_method: Optional[Callable] = mimetypes.guess_type, **kwargs)

Source code in cloudpathlib/local/localclient.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def __init__(
    self,
    *args,
    local_storage_dir: Optional[Union[str, os.PathLike]] = None,
    file_cache_mode: Optional[Union[str, FileCacheMode]] = None,
    local_cache_dir: Optional[Union[str, os.PathLike]] = None,
    content_type_method: Optional[Callable] = mimetypes.guess_type,
    **kwargs,
):
    self._local_storage_dir = local_storage_dir

    super().__init__(
        local_cache_dir=local_cache_dir,
        content_type_method=content_type_method,
        file_cache_mode=file_cache_mode,
    )

clear_cache()

Clears the contents of the cache folder. Does not remove folder so it can keep being written to.

Source code in cloudpathlib/client.py 
114
115
116
117
118
119
120
121
122
123
def clear_cache(self):
    """Clears the contents of the cache folder.
    Does not remove folder so it can keep being written to.
    """
    if self._local_cache_dir.exists():
        for p in self._local_cache_dir.iterdir():
            if p.is_file():
                p.unlink()
            else:
                shutil.rmtree(p)

get_default_client() -> Client[BoundedCloudPath] classmethod

Get the default client, which the one that is used when instantiating a cloud path instance for this cloud without a client specified.

Source code in cloudpathlib/client.py 
 97
 98
 99
100
101
102
103
104
@classmethod
def get_default_client(cls) -> "Client[BoundedCloudPath]":
    """Get the default client, which the one that is used when instantiating a cloud path
    instance for this cloud without a client specified.
    """
    if cls._default_client is None:
        cls._default_client = cls()
    return cls._default_client

get_default_storage_dir() -> Path classmethod

Return the default storage directory for this client class. This is used if a client is instantiated without a storage directory being explicitly provided. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
46
47
48
49
50
51
52
53
54
55
@classmethod
def get_default_storage_dir(cls) -> Path:
    """Return the default storage directory for this client class. This is used if a client
    is instantiated without a storage directory being explicitly provided. In this usage,
    "storage" refers to the local storage that simulates the cloud.
    """
    if cls._default_storage_temp_dir is None:
        cls._default_storage_temp_dir = TemporaryDirectory()
        _temp_dirs_to_clean.append(cls._default_storage_temp_dir)
    return Path(cls._default_storage_temp_dir.name)

reset_default_storage_dir() -> Path classmethod

Reset the default storage directly. This tears down and recreates the directory used by default for this client class when instantiating a client without explicitly providing a storage directory. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
57
58
59
60
61
62
63
64
65
@classmethod
def reset_default_storage_dir(cls) -> Path:
    """Reset the default storage directly. This tears down and recreates the directory used by
    default for this client class when instantiating a client without explicitly providing
    a storage directory. In this usage, "storage" refers to the local storage that simulates
    the cloud.
    """
    cls._default_storage_temp_dir = None
    return cls.get_default_storage_dir()

set_as_default_client() -> None

Set this client instance as the default one used when instantiating cloud path instances for this cloud without a client specified.

Source code in cloudpathlib/client.py 
106
107
108
109
def set_as_default_client(self) -> None:
    """Set this client instance as the default one used when instantiating cloud path
    instances for this cloud without a client specified."""
    self.__class__._default_client = self

Bases: LocalPath

Replacement for GSPath that uses the local file system. Intended as a monkeypatch substitute when writing tests.

Source code in cloudpathlib/local/implementations/gs.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
class LocalGSPath(LocalPath):
    """Replacement for GSPath that uses the local file system. Intended as a monkeypatch substitute
    when writing tests.
    """

    cloud_prefix: str = "gs://"
    _cloud_meta = local_gs_implementation

    @property
    def drive(self) -> str:
        return self.bucket

    def mkdir(self, parents=False, exist_ok=False, mode: Optional[Any] = None):
        # not possible to make empty directory on gs
        pass

    @property
    def bucket(self) -> str:
        return self._no_prefix.split("/", 1)[0]

    @property
    def blob(self) -> str:
        key = self._no_prefix_no_drive

        # key should never have starting slash for
        # use with boto, etc.
        if key.startswith("/"):
            key = key[1:]

        return key

    @property
    def etag(self):
        return self.client._md5(self)

    @property
    def md5(self) -> str:
        return self.client._md5(self)

Attributes

anchor: str property

blob: str property

bucket: str property

client: LocalClient instance-attribute

cloud_prefix: str = 'gs://' class-attribute instance-attribute

drive: str property

etag property

fspath: str property

md5: str property

name: str property

parent: Self property

parents: Tuple[Self, ...] property

parser: Self property

parts: Tuple[str, ...] property

stem: str property

suffix: str property

suffixes: List[str] property

Methods:

__init__(cloud_path: Union[str, Self, CloudPath], *parts: str, client: Optional[Client] = None) -> None

Source code in cloudpathlib/cloudpath.py 
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
def __init__(
    self,
    cloud_path: Union[str, Self, "CloudPath"],
    *parts: str,
    client: Optional["Client"] = None,
) -> None:
    # handle if local file gets opened. must be set at the top of the method in case any code
    # below raises an exception, this prevents __del__ from raising an AttributeError
    self._handle: Optional[IO] = None
    self._client: Optional["Client"] = None

    if parts:
        # ensure first part ends in "/"; (sometimes it is just prefix, sometimes a longer path)
        if not str(cloud_path).endswith("/"):
            cloud_path = str(cloud_path) + "/"

        cloud_path = str(cloud_path) + "/".join(p.strip("/") for p in parts)

    self.is_valid_cloudpath(cloud_path, raise_on_error=True)
    self._cloud_meta.validate_completeness()

    # 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):
            self._client = cloud_path.client
    else:
        self._client = client

    if client is not None and 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."
        )

    # track if local has been written to, if so it may need to be uploaded
    self._dirty = False

absolute() -> Self

Source code in cloudpathlib/cloudpath.py 
1012
1013
def absolute(self) -> Self:
    return self

as_uri() -> str

Source code in cloudpathlib/cloudpath.py 
444
445
def as_uri(self) -> str:
    return str(self)

as_url(presign: bool = False, expire_seconds: int = 60 * 60) -> str

Source code in cloudpathlib/cloudpath.py 
426
427
428
429
430
431
def as_url(self, presign: bool = False, expire_seconds: int = 60 * 60) -> str:
    if presign:
        url = self.client._generate_presigned_url(self, expire_seconds=expire_seconds)
    else:
        url = self.client._get_public_url(self)
    return url

clear_cache()

Removes cache if it exists

Source code in cloudpathlib/cloudpath.py 
1525
1526
1527
1528
1529
1530
1531
def clear_cache(self):
    """Removes cache if it exists"""
    if self._local.exists():
        if self._local.is_file():
            self._local.unlink()
        else:
            shutil.rmtree(self._local)

copy(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

copy(
    target: Self,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy(
    target: Path,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy(
    target: str,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self to target folder or file, if self is a file.

Source code in cloudpathlib/cloudpath.py 
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
def copy(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self to target folder or file, if self is a file."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )

copy_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

copy_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self into target directory, preserving the filename.

Source code in cloudpathlib/cloudpath.py 
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
def copy_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self into target directory, preserving the filename."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )
    return cast(Union[Path, Self], result)

copytree(destination, force_overwrite_to_cloud=None, ignore=None) 

copytree(
    destination: Self,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Self

copytree(
    destination: Path,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Path

copytree(
    destination: Union[str, os.PathLike, Self],
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Union[Path, CloudPath]

Copy self to a directory, if self is a directory.

Source code in cloudpathlib/cloudpath.py 
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
def copytree(self, destination, force_overwrite_to_cloud=None, ignore=None):
    """Copy self to a directory, if self is a directory."""
    if not self.is_dir():
        raise CloudPathNotADirectoryError(
            f"Origin path {self} must be a directory. To copy a single file use the method copy."
        )

    destination = anypath.to_anypath(destination)

    if destination.exists() and destination.is_file():
        raise CloudPathFileExistsError(
            f"Destination path {destination} of copytree must be a directory."
        )

    contents = list(self.iterdir())

    if ignore is not None:
        ignored_names = ignore(self._no_prefix_no_drive, [x.name for x in contents])
    else:
        ignored_names = set()

    destination.mkdir(parents=True, exist_ok=True)

    for subpath in contents:
        if subpath.name in ignored_names:
            continue
        if subpath.is_file():
            subpath.copy(
                destination / subpath.name, force_overwrite_to_cloud=force_overwrite_to_cloud
            )
        elif subpath.is_dir():
            subpath.copytree(
                destination / (subpath.name + ("" if subpath.name.endswith("/") else "/")),
                force_overwrite_to_cloud=force_overwrite_to_cloud,
                ignore=ignore,
            )

    return destination

download_to(destination: Union[str, os.PathLike]) -> Path

Source code in cloudpathlib/cloudpath.py 
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
def download_to(self, destination: Union[str, os.PathLike]) -> Path:
    destination = Path(destination)

    if not self.exists():
        raise CloudPathNotExistsError(f"Cannot download because path does not exist: {self}")

    if self.is_file():
        if destination.is_dir():
            destination = destination / self.name
        return 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)

        return destination

exists(follow_symlinks=True) -> bool

Source code in cloudpathlib/cloudpath.py 
447
448
def exists(self, follow_symlinks=True) -> bool:
    return self.client._exists(self)

from_uri(uri: str) -> Self classmethod

Source code in cloudpathlib/cloudpath.py 
460
461
462
@classmethod
def from_uri(cls, uri: str) -> Self:
    return cls(uri)

full_match(pattern: str, case_sensitive: Optional[bool] = None) -> bool

Source code in cloudpathlib/cloudpath.py 
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
def full_match(self, pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    if sys.version_info < (3, 13):
        raise NotImplementedError("full_match requires Python 3.13 or higher")

    # strip scheme from start of pattern before testing
    if pattern.startswith(self.anchor + self.drive):
        pattern = pattern[len(self.anchor + self.drive) :]
    elif pattern.startswith(self.anchor):
        # for http paths, keep leading slash
        pattern = pattern[len(self.anchor) - 1 :]

    # remove drive, which is kept on normal dispatch to pathlib
    return PurePosixPath(self._no_prefix_no_drive).full_match(  # type: ignore[attr-defined]
        pattern, case_sensitive=case_sensitive
    )

glob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]

Source code in cloudpathlib/cloudpath.py 
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
def glob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(
        selector,
        "/" in pattern
        or "**"
        in pattern,  # recursive listing needed if explicit ** or any sub folder in pattern
    )

info() -> CloudPathInfo

Return a CloudPathInfo object for this path.

Source code in cloudpathlib/cloudpath.py 
1163
1164
1165
def info(self) -> "CloudPathInfo":
    """Return a CloudPathInfo object for this path."""
    return CloudPathInfo(self)

is_absolute() -> bool

Source code in cloudpathlib/cloudpath.py 
1015
1016
def is_absolute(self) -> bool:
    return True

is_dir(follow_symlinks=True) -> bool

Source code in cloudpathlib/local/localpath.py 
15
16
def is_dir(self, follow_symlinks=True) -> bool:
    return self.client._is_dir(self, follow_symlinks=follow_symlinks)

is_file(follow_symlinks=True) -> bool

Source code in cloudpathlib/local/localpath.py 
18
19
def is_file(self, follow_symlinks=True) -> bool:
    return self.client._is_file(self, follow_symlinks=follow_symlinks)

is_junction()

Source code in cloudpathlib/cloudpath.py 
959
960
def is_junction(self):
    return False  # only windows paths can be junctions, not cloudpaths

is_relative_to(other: Self) -> bool

Source code in cloudpathlib/cloudpath.py 
1038
1039
1040
1041
1042
1043
def is_relative_to(self, other: Self) -> bool:
    try:
        self.relative_to(other)
        return True
    except ValueError:
        return False

is_valid_cloudpath(path: Union[str, CloudPath], raise_on_error: bool = False) -> Union[bool, TypeGuard[Self]] classmethod 

is_valid_cloudpath(
    path: CloudPath, raise_on_error: bool = ...
) -> TypeGuard[Self]

is_valid_cloudpath(
    path: str, raise_on_error: bool = ...
) -> bool
Source code in cloudpathlib/cloudpath.py 
332
333
334
335
336
337
338
339
340
341
342
343
@classmethod
def is_valid_cloudpath(
    cls, path: Union[str, "CloudPath"], raise_on_error: bool = False
) -> Union[bool, TypeGuard[Self]]:
    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() -> Generator[Self, None, None]

Source code in cloudpathlib/cloudpath.py 
579
580
581
582
def iterdir(self) -> Generator[Self, None, None]:
    for f, _ in self.client._list_dir(self, recursive=False):
        if f != self:  # iterdir does not include itself in pathlib
            yield f

joinpath(*pathsegments: Union[str, os.PathLike]) -> Self

Source code in cloudpathlib/cloudpath.py 
1009
1010
def joinpath(self, *pathsegments: Union[str, os.PathLike]) -> Self:
    return self._dispatch_to_path("joinpath", *pathsegments)

match(path_pattern: str, case_sensitive: Optional[bool] = None) -> bool

Source code in cloudpathlib/cloudpath.py 
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
def match(self, path_pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    # 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 + "/") :]

    kwargs = dict(case_sensitive=case_sensitive)

    if sys.version_info < (3, 12):
        kwargs.pop("case_sensitive")

    return self._dispatch_to_path("match", path_pattern, **kwargs)

mkdir(parents=False, exist_ok=False, mode: Optional[Any] = None)

Source code in cloudpathlib/local/implementations/gs.py 
34
35
36
def mkdir(self, parents=False, exist_ok=False, mode: Optional[Any] = None):
    # not possible to make empty directory on gs
    pass

move(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

move(
    target: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move(
    target: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move(
    target: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self to target location, removing the source.

Source code in cloudpathlib/cloudpath.py 
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
def move(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self to target location, removing the source."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )

move_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

move_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self into target directory, preserving the filename and removing the source.

Source code in cloudpathlib/cloudpath.py 
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
def move_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self into target directory, preserving the filename and removing the source."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )
    return cast(Union[Path, Self], result)

open(mode: str = 'r', buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, force_overwrite_from_cloud: Optional[bool] = None, force_overwrite_to_cloud: Optional[bool] = None) -> IO[Any] 

open(
    mode: OpenTextMode = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> TextIOWrapper

open(
    mode: OpenBinaryMode,
    buffering: Literal[0],
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> FileIO

open(
    mode: OpenBinaryModeUpdating,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedRandom

open(
    mode: OpenBinaryModeWriting,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedWriter

open(
    mode: OpenBinaryModeReading,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedReader

open(
    mode: OpenBinaryMode,
    buffering: int = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BinaryIO

open(
    mode: str,
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> IO[Any]
Source code in cloudpathlib/cloudpath.py 
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
def open(
    self,
    mode: str = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
    force_overwrite_to_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
) -> "IO[Any]":
    # if trying to call open on a directory that exists
    exists_on_cloud = self.exists()

    if exists_on_cloud and not self.is_file():
        raise CloudPathIsADirectoryError(
            f"Cannot open directory, only files. Tried to open ({self})"
        )

    if not exists_on_cloud and any(m in mode for m in ("r", "a")):
        raise CloudPathFileNotFoundError(
            f"File opened for read or append, but it does not exist on cloud: {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.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
        wrapped_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_upload(*args, **kwargs) -> None:
            wrapped_close(*args, **kwargs)

            # we should be idempotent and not upload again if
            # we already ran our close method patch
            if not self._dirty:
                return

            # 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)
            self._dirty = False

        buffer.close = _patched_close_upload  # type: ignore

        # 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

    # if we don't want any cache around, remove the cache
    # as soon as the file is closed
    if self.client.file_cache_mode == FileCacheMode.close_file:
        # this may be _patched_close_upload, in which case we need to
        # make sure to call that first so the file gets uploaded
        wrapped_close_for_cache = buffer.close

        def _patched_close_empty_cache(*args, **kwargs):
            wrapped_close_for_cache(*args, **kwargs)

            # remove local file as last step on closing
            self.clear_cache()

        buffer.close = _patched_close_empty_cache  # type: ignore

    return buffer

read_bytes() -> bytes

Source code in cloudpathlib/cloudpath.py 
946
947
948
def read_bytes(self) -> bytes:
    with self.open(mode="rb") as f:
        return f.read()

read_text(encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> str

Source code in cloudpathlib/cloudpath.py 
950
951
952
953
954
955
956
957
def read_text(
    self,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> str:
    with self.open(mode="r", encoding=encoding, errors=errors, newline=newline) as f:
        return f.read()

relative_to(other: Self, walk_up: bool = False) -> PurePosixPath

Source code in cloudpathlib/cloudpath.py 
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
def relative_to(self, other: Self, walk_up: bool = False) -> PurePosixPath:
    # We don't dispatch regularly since this never returns a cloud path (since it is relative, and cloud paths are
    # absolute)
    if not isinstance(other, CloudPath):
        raise ValueError(f"{self} is a cloud path, but {other} is not")
    if self.anchor != other.anchor:
        raise ValueError(
            f"{self} is a {self.anchor} path, but {other} is a {other.anchor} path"
        )

    kwargs = dict(walk_up=walk_up)

    if sys.version_info < (3, 12):
        kwargs.pop("walk_up")

    return self._path.relative_to(other._path, **kwargs)  # type: ignore[call-arg]

rename(target: Self) -> Self

Source code in cloudpathlib/cloudpath.py 
886
887
888
889
def rename(self, target: Self) -> Self:
    # for cloud services replace == rename since we don't just rename,
    # we actually move files
    return self.replace(target)

replace(target: Self) -> Self

Source code in cloudpathlib/cloudpath.py 
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
def replace(self, target: Self) -> Self:
    if type(self) is not type(target):
        raise TypeError(
            f"The target based to rename must be an instantiated class of type: {type(self)}"
        )

    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; rename/replace the files recursively."
        )

    if target == self:
        # Request is to replace/rename this with the same path - nothing to do
        return self

    if target.exists():
        target.unlink()

    self.client._move_file(self, target)
    return target

resolve(strict: bool = False) -> Self

Source code in cloudpathlib/cloudpath.py 
1018
1019
def resolve(self, strict: bool = False) -> Self:
    return self

rglob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]

Source code in cloudpathlib/cloudpath.py 
564
565
566
567
568
569
570
571
572
573
574
575
576
577
def rglob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        ("**",) + tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(selector, True)

rmdir() -> None

Source code in cloudpathlib/cloudpath.py 
891
892
893
894
895
896
897
898
899
900
901
902
903
def rmdir(self) -> None:
    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() -> None

Delete an entire directory tree.

Source code in cloudpathlib/cloudpath.py 
1190
1191
1192
1193
1194
1195
1196
def rmtree(self) -> None:
    """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(other_path: Union[str, os.PathLike]) -> bool

Source code in cloudpathlib/cloudpath.py 
905
906
907
def samefile(self, other_path: Union[str, os.PathLike]) -> bool:
    # all cloud paths are absolute and the paths are used for hash
    return self == other_path

stat(follow_symlinks=True)

Source code in cloudpathlib/local/localpath.py 
21
22
23
24
25
26
27
28
def stat(self, follow_symlinks=True):
    try:
        meta = self.client._stat(self)
    except FileNotFoundError:
        raise NoStatError(
            f"No stats available for {self}; it may be a directory or not exist."
        )
    return meta

touch(exist_ok: bool = True, mode: Optional[Any] = None)

Source code in cloudpathlib/local/localpath.py 
30
31
def touch(self, exist_ok: bool = True, mode: Optional[Any] = None):
    self.client._touch(self, exist_ok)
Source code in cloudpathlib/cloudpath.py 
909
910
911
912
913
914
915
def unlink(self, missing_ok: bool = True) -> None:
    # Note: missing_ok defaults to False in pathlib, but changing the default now would be a breaking change.
    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; call rmdir instead of unlink."
        )
    self.client._remove(self, missing_ok)

upload_from(source: Union[str, os.PathLike], force_overwrite_to_cloud: Optional[bool] = None) -> Self

Upload a file or directory to the cloud path.

Source code in cloudpathlib/cloudpath.py 
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
def upload_from(
    self,
    source: Union[str, os.PathLike],
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self:
    """Upload a file or directory to the cloud path."""
    source = Path(source)

    if source.is_dir():
        for p in source.iterdir():
            (self / p.name).upload_from(p, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return self

    else:
        if self.exists() and self.is_dir():
            dst = self / source.name
        else:
            dst = self

        dst._upload_file_to_cloud(source, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return dst

validate(v: str) -> Self classmethod

Used as a Pydantic validator. See https://docs.pydantic.dev/2.0/usage/types/custom/

Source code in cloudpathlib/cloudpath.py 
1687
1688
1689
1690
1691
@classmethod
def validate(cls, v: str) -> Self:
    """Used as a Pydantic validator. See
    https://docs.pydantic.dev/2.0/usage/types/custom/"""
    return cls(v)

walk(top_down: bool = True, on_error: Optional[Callable] = None, follow_symlinks: bool = False, lazy: bool = False) -> Generator[Tuple[Self, List[str], List[str]], None, None]

Walk the directory tree rooted at this path, similar to :meth:pathlib.Path.walk and :func:os.walk.

By default (lazy=False) the entire subtree is listed up front with a single recursive listing, which is the fastest option for a full walk on cloud backends.

Pass lazy=True to defer listing until each directory is visited (one non-recursive listing per directory). This is slower for a full walk, but lets callers prune dirnames in place (when top_down=True) to avoid fetching the contents of skipped subtrees entirely -- which can be dramatically faster and cheaper for sparse traversals.

follow_symlinks is accepted for signature parity with pathlib but has no effect on cloud backends, which do not have symlinks.

Source code in cloudpathlib/cloudpath.py 
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def walk(
    self,
    top_down: bool = True,
    on_error: Optional[Callable] = None,
    follow_symlinks: bool = False,
    lazy: bool = False,
) -> Generator[Tuple[Self, List[str], List[str]], None, None]:
    """Walk the directory tree rooted at this path, similar to
    :meth:`pathlib.Path.walk` and :func:`os.walk`.

    By default (``lazy=False``) the entire subtree is listed up front with a
    single recursive listing, which is the fastest option for a full walk on
    cloud backends.

    Pass ``lazy=True`` to defer listing until each directory is visited (one
    non-recursive listing per directory). This is slower for a full walk,
    but lets callers prune ``dirnames`` in place (when ``top_down=True``) to
    avoid fetching the contents of skipped subtrees entirely -- which can be
    dramatically faster and cheaper for sparse traversals.

    ``follow_symlinks`` is accepted for signature parity with ``pathlib``
    but has no effect on cloud backends, which do not have symlinks.
    """
    if lazy:
        yield from self._walk_lazy(top_down=top_down, on_error=on_error)
        return

    try:
        file_tree = self._build_subtree(recursive=True)  # walking is always recursive
        yield from self._walk_results_from_tree(self, file_tree, top_down=top_down)

    except Exception as e:
        if on_error is not None:
            on_error(e)
        else:
            raise

with_name(name: str) -> Self

Source code in cloudpathlib/cloudpath.py 
1119
1120
def with_name(self, name: str) -> Self:
    return self._dispatch_to_path("with_name", name)

with_segments(*pathsegments) -> Self

Create a new CloudPath with the same client out of the given segments. The first segment will be interpreted as the bucket/container name.

Source code in cloudpathlib/cloudpath.py 
1122
1123
1124
1125
1126
def with_segments(self, *pathsegments) -> Self:
    """Create a new CloudPath with the same client out of the given segments.
    The first segment will be interpreted as the bucket/container name.
    """
    return self._new_cloudpath("/".join(pathsegments))

with_stem(stem: str) -> Self

Source code in cloudpathlib/cloudpath.py 
1112
1113
1114
1115
1116
1117
def with_stem(self, stem: str) -> Self:
    try:
        return self._dispatch_to_path("with_stem", stem)
    except AttributeError:
        # with_stem was only added in python 3.9, so we fallback for compatibility
        return self.with_name(stem + self.suffix)

with_suffix(suffix: str) -> Self

Source code in cloudpathlib/cloudpath.py 
1128
1129
def with_suffix(self, suffix: str) -> Self:
    return self._dispatch_to_path("with_suffix", suffix)

write_bytes(data: bytes) -> int

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

Source code in cloudpathlib/cloudpath.py 
917
918
919
920
921
922
923
924
925
926
def write_bytes(self, data: bytes) -> int:
    """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(data: str, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> int

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.10/Lib/pathlib.py#L1146-L1155

Source code in cloudpathlib/cloudpath.py 
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
def write_text(
    self,
    data: str,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> int:
    """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.10/Lib/pathlib.py#L1146-L1155
    """
    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, newline=newline) as f:
        return f.write(data)

Bases: CloudPath

Abstract CloudPath for accessing objects the local filesystem. Subclasses are as a monkeypatch substitutes for normal CloudPath subclasses when writing tests.

Source code in cloudpathlib/local/localpath.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
class LocalPath(CloudPath):
    """Abstract CloudPath for accessing objects the local filesystem. Subclasses are as a
    monkeypatch substitutes for normal CloudPath subclasses when writing tests."""

    client: "LocalClient"

    def is_dir(self, follow_symlinks=True) -> bool:
        return self.client._is_dir(self, follow_symlinks=follow_symlinks)

    def is_file(self, follow_symlinks=True) -> bool:
        return self.client._is_file(self, follow_symlinks=follow_symlinks)

    def stat(self, follow_symlinks=True):
        try:
            meta = self.client._stat(self)
        except FileNotFoundError:
            raise NoStatError(
                f"No stats available for {self}; it may be a directory or not exist."
            )
        return meta

    def touch(self, exist_ok: bool = True, mode: Optional[Any] = None):
        self.client._touch(self, exist_ok)

Attributes

anchor: str property

client: LocalClient instance-attribute

cloud_prefix: str instance-attribute

drive: str abstractmethod property

For example "bucket" on S3 or "container" on Azure; needs to be defined for each class

fspath: str property

name: str property

parent: Self property

parents: Tuple[Self, ...] property

parser: Self property

parts: Tuple[str, ...] property

stem: str property

suffix: str property

suffixes: List[str] property

Methods:

__init__(cloud_path: Union[str, Self, CloudPath], *parts: str, client: Optional[Client] = None) -> None

Source code in cloudpathlib/cloudpath.py 
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
def __init__(
    self,
    cloud_path: Union[str, Self, "CloudPath"],
    *parts: str,
    client: Optional["Client"] = None,
) -> None:
    # handle if local file gets opened. must be set at the top of the method in case any code
    # below raises an exception, this prevents __del__ from raising an AttributeError
    self._handle: Optional[IO] = None
    self._client: Optional["Client"] = None

    if parts:
        # ensure first part ends in "/"; (sometimes it is just prefix, sometimes a longer path)
        if not str(cloud_path).endswith("/"):
            cloud_path = str(cloud_path) + "/"

        cloud_path = str(cloud_path) + "/".join(p.strip("/") for p in parts)

    self.is_valid_cloudpath(cloud_path, raise_on_error=True)
    self._cloud_meta.validate_completeness()

    # 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):
            self._client = cloud_path.client
    else:
        self._client = client

    if client is not None and 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."
        )

    # track if local has been written to, if so it may need to be uploaded
    self._dirty = False

absolute() -> Self

Source code in cloudpathlib/cloudpath.py 
1012
1013
def absolute(self) -> Self:
    return self

as_uri() -> str

Source code in cloudpathlib/cloudpath.py 
444
445
def as_uri(self) -> str:
    return str(self)

as_url(presign: bool = False, expire_seconds: int = 60 * 60) -> str

Source code in cloudpathlib/cloudpath.py 
426
427
428
429
430
431
def as_url(self, presign: bool = False, expire_seconds: int = 60 * 60) -> str:
    if presign:
        url = self.client._generate_presigned_url(self, expire_seconds=expire_seconds)
    else:
        url = self.client._get_public_url(self)
    return url

clear_cache()

Removes cache if it exists

Source code in cloudpathlib/cloudpath.py 
1525
1526
1527
1528
1529
1530
1531
def clear_cache(self):
    """Removes cache if it exists"""
    if self._local.exists():
        if self._local.is_file():
            self._local.unlink()
        else:
            shutil.rmtree(self._local)

copy(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

copy(
    target: Self,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy(
    target: Path,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy(
    target: str,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self to target folder or file, if self is a file.

Source code in cloudpathlib/cloudpath.py 
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
def copy(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self to target folder or file, if self is a file."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )

copy_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

copy_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self into target directory, preserving the filename.

Source code in cloudpathlib/cloudpath.py 
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
def copy_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self into target directory, preserving the filename."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )
    return cast(Union[Path, Self], result)

copytree(destination, force_overwrite_to_cloud=None, ignore=None) 

copytree(
    destination: Self,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Self

copytree(
    destination: Path,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Path

copytree(
    destination: Union[str, os.PathLike, Self],
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Union[Path, CloudPath]

Copy self to a directory, if self is a directory.

Source code in cloudpathlib/cloudpath.py 
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
def copytree(self, destination, force_overwrite_to_cloud=None, ignore=None):
    """Copy self to a directory, if self is a directory."""
    if not self.is_dir():
        raise CloudPathNotADirectoryError(
            f"Origin path {self} must be a directory. To copy a single file use the method copy."
        )

    destination = anypath.to_anypath(destination)

    if destination.exists() and destination.is_file():
        raise CloudPathFileExistsError(
            f"Destination path {destination} of copytree must be a directory."
        )

    contents = list(self.iterdir())

    if ignore is not None:
        ignored_names = ignore(self._no_prefix_no_drive, [x.name for x in contents])
    else:
        ignored_names = set()

    destination.mkdir(parents=True, exist_ok=True)

    for subpath in contents:
        if subpath.name in ignored_names:
            continue
        if subpath.is_file():
            subpath.copy(
                destination / subpath.name, force_overwrite_to_cloud=force_overwrite_to_cloud
            )
        elif subpath.is_dir():
            subpath.copytree(
                destination / (subpath.name + ("" if subpath.name.endswith("/") else "/")),
                force_overwrite_to_cloud=force_overwrite_to_cloud,
                ignore=ignore,
            )

    return destination

download_to(destination: Union[str, os.PathLike]) -> Path

Source code in cloudpathlib/cloudpath.py 
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
def download_to(self, destination: Union[str, os.PathLike]) -> Path:
    destination = Path(destination)

    if not self.exists():
        raise CloudPathNotExistsError(f"Cannot download because path does not exist: {self}")

    if self.is_file():
        if destination.is_dir():
            destination = destination / self.name
        return 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)

        return destination

exists(follow_symlinks=True) -> bool

Source code in cloudpathlib/cloudpath.py 
447
448
def exists(self, follow_symlinks=True) -> bool:
    return self.client._exists(self)

from_uri(uri: str) -> Self classmethod

Source code in cloudpathlib/cloudpath.py 
460
461
462
@classmethod
def from_uri(cls, uri: str) -> Self:
    return cls(uri)

full_match(pattern: str, case_sensitive: Optional[bool] = None) -> bool

Source code in cloudpathlib/cloudpath.py 
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
def full_match(self, pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    if sys.version_info < (3, 13):
        raise NotImplementedError("full_match requires Python 3.13 or higher")

    # strip scheme from start of pattern before testing
    if pattern.startswith(self.anchor + self.drive):
        pattern = pattern[len(self.anchor + self.drive) :]
    elif pattern.startswith(self.anchor):
        # for http paths, keep leading slash
        pattern = pattern[len(self.anchor) - 1 :]

    # remove drive, which is kept on normal dispatch to pathlib
    return PurePosixPath(self._no_prefix_no_drive).full_match(  # type: ignore[attr-defined]
        pattern, case_sensitive=case_sensitive
    )

glob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]

Source code in cloudpathlib/cloudpath.py 
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
def glob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(
        selector,
        "/" in pattern
        or "**"
        in pattern,  # recursive listing needed if explicit ** or any sub folder in pattern
    )

info() -> CloudPathInfo

Return a CloudPathInfo object for this path.

Source code in cloudpathlib/cloudpath.py 
1163
1164
1165
def info(self) -> "CloudPathInfo":
    """Return a CloudPathInfo object for this path."""
    return CloudPathInfo(self)

is_absolute() -> bool

Source code in cloudpathlib/cloudpath.py 
1015
1016
def is_absolute(self) -> bool:
    return True

is_dir(follow_symlinks=True) -> bool

Source code in cloudpathlib/local/localpath.py 
15
16
def is_dir(self, follow_symlinks=True) -> bool:
    return self.client._is_dir(self, follow_symlinks=follow_symlinks)

is_file(follow_symlinks=True) -> bool

Source code in cloudpathlib/local/localpath.py 
18
19
def is_file(self, follow_symlinks=True) -> bool:
    return self.client._is_file(self, follow_symlinks=follow_symlinks)

is_junction()

Source code in cloudpathlib/cloudpath.py 
959
960
def is_junction(self):
    return False  # only windows paths can be junctions, not cloudpaths

is_relative_to(other: Self) -> bool

Source code in cloudpathlib/cloudpath.py 
1038
1039
1040
1041
1042
1043
def is_relative_to(self, other: Self) -> bool:
    try:
        self.relative_to(other)
        return True
    except ValueError:
        return False

is_valid_cloudpath(path: Union[str, CloudPath], raise_on_error: bool = False) -> Union[bool, TypeGuard[Self]] classmethod 

is_valid_cloudpath(
    path: CloudPath, raise_on_error: bool = ...
) -> TypeGuard[Self]

is_valid_cloudpath(
    path: str, raise_on_error: bool = ...
) -> bool
Source code in cloudpathlib/cloudpath.py 
332
333
334
335
336
337
338
339
340
341
342
343
@classmethod
def is_valid_cloudpath(
    cls, path: Union[str, "CloudPath"], raise_on_error: bool = False
) -> Union[bool, TypeGuard[Self]]:
    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() -> Generator[Self, None, None]

Source code in cloudpathlib/cloudpath.py 
579
580
581
582
def iterdir(self) -> Generator[Self, None, None]:
    for f, _ in self.client._list_dir(self, recursive=False):
        if f != self:  # iterdir does not include itself in pathlib
            yield f

joinpath(*pathsegments: Union[str, os.PathLike]) -> Self

Source code in cloudpathlib/cloudpath.py 
1009
1010
def joinpath(self, *pathsegments: Union[str, os.PathLike]) -> Self:
    return self._dispatch_to_path("joinpath", *pathsegments)

match(path_pattern: str, case_sensitive: Optional[bool] = None) -> bool

Source code in cloudpathlib/cloudpath.py 
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
def match(self, path_pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    # 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 + "/") :]

    kwargs = dict(case_sensitive=case_sensitive)

    if sys.version_info < (3, 12):
        kwargs.pop("case_sensitive")

    return self._dispatch_to_path("match", path_pattern, **kwargs)

mkdir(parents: bool = False, exist_ok: bool = False, mode: Optional[Any] = None) -> None abstractmethod

Should be implemented using the client API without requiring a dir is downloaded

Source code in cloudpathlib/cloudpath.py 
414
415
416
417
418
419
@abc.abstractmethod
def mkdir(
    self, parents: bool = False, exist_ok: bool = False, mode: Optional[Any] = None
) -> None:
    """Should be implemented using the client API without requiring a dir is downloaded"""
    pass

move(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

move(
    target: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move(
    target: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move(
    target: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self to target location, removing the source.

Source code in cloudpathlib/cloudpath.py 
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
def move(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self to target location, removing the source."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )

move_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

move_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self into target directory, preserving the filename and removing the source.

Source code in cloudpathlib/cloudpath.py 
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
def move_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self into target directory, preserving the filename and removing the source."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )
    return cast(Union[Path, Self], result)

open(mode: str = 'r', buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, force_overwrite_from_cloud: Optional[bool] = None, force_overwrite_to_cloud: Optional[bool] = None) -> IO[Any] 

open(
    mode: OpenTextMode = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> TextIOWrapper

open(
    mode: OpenBinaryMode,
    buffering: Literal[0],
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> FileIO

open(
    mode: OpenBinaryModeUpdating,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedRandom

open(
    mode: OpenBinaryModeWriting,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedWriter

open(
    mode: OpenBinaryModeReading,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedReader

open(
    mode: OpenBinaryMode,
    buffering: int = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BinaryIO

open(
    mode: str,
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> IO[Any]
Source code in cloudpathlib/cloudpath.py 
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
def open(
    self,
    mode: str = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
    force_overwrite_to_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
) -> "IO[Any]":
    # if trying to call open on a directory that exists
    exists_on_cloud = self.exists()

    if exists_on_cloud and not self.is_file():
        raise CloudPathIsADirectoryError(
            f"Cannot open directory, only files. Tried to open ({self})"
        )

    if not exists_on_cloud and any(m in mode for m in ("r", "a")):
        raise CloudPathFileNotFoundError(
            f"File opened for read or append, but it does not exist on cloud: {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.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
        wrapped_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_upload(*args, **kwargs) -> None:
            wrapped_close(*args, **kwargs)

            # we should be idempotent and not upload again if
            # we already ran our close method patch
            if not self._dirty:
                return

            # 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)
            self._dirty = False

        buffer.close = _patched_close_upload  # type: ignore

        # 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

    # if we don't want any cache around, remove the cache
    # as soon as the file is closed
    if self.client.file_cache_mode == FileCacheMode.close_file:
        # this may be _patched_close_upload, in which case we need to
        # make sure to call that first so the file gets uploaded
        wrapped_close_for_cache = buffer.close

        def _patched_close_empty_cache(*args, **kwargs):
            wrapped_close_for_cache(*args, **kwargs)

            # remove local file as last step on closing
            self.clear_cache()

        buffer.close = _patched_close_empty_cache  # type: ignore

    return buffer

read_bytes() -> bytes

Source code in cloudpathlib/cloudpath.py 
946
947
948
def read_bytes(self) -> bytes:
    with self.open(mode="rb") as f:
        return f.read()

read_text(encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> str

Source code in cloudpathlib/cloudpath.py 
950
951
952
953
954
955
956
957
def read_text(
    self,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> str:
    with self.open(mode="r", encoding=encoding, errors=errors, newline=newline) as f:
        return f.read()

relative_to(other: Self, walk_up: bool = False) -> PurePosixPath

Source code in cloudpathlib/cloudpath.py 
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
def relative_to(self, other: Self, walk_up: bool = False) -> PurePosixPath:
    # We don't dispatch regularly since this never returns a cloud path (since it is relative, and cloud paths are
    # absolute)
    if not isinstance(other, CloudPath):
        raise ValueError(f"{self} is a cloud path, but {other} is not")
    if self.anchor != other.anchor:
        raise ValueError(
            f"{self} is a {self.anchor} path, but {other} is a {other.anchor} path"
        )

    kwargs = dict(walk_up=walk_up)

    if sys.version_info < (3, 12):
        kwargs.pop("walk_up")

    return self._path.relative_to(other._path, **kwargs)  # type: ignore[call-arg]

rename(target: Self) -> Self

Source code in cloudpathlib/cloudpath.py 
886
887
888
889
def rename(self, target: Self) -> Self:
    # for cloud services replace == rename since we don't just rename,
    # we actually move files
    return self.replace(target)

replace(target: Self) -> Self

Source code in cloudpathlib/cloudpath.py 
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
def replace(self, target: Self) -> Self:
    if type(self) is not type(target):
        raise TypeError(
            f"The target based to rename must be an instantiated class of type: {type(self)}"
        )

    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; rename/replace the files recursively."
        )

    if target == self:
        # Request is to replace/rename this with the same path - nothing to do
        return self

    if target.exists():
        target.unlink()

    self.client._move_file(self, target)
    return target

resolve(strict: bool = False) -> Self

Source code in cloudpathlib/cloudpath.py 
1018
1019
def resolve(self, strict: bool = False) -> Self:
    return self

rglob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]

Source code in cloudpathlib/cloudpath.py 
564
565
566
567
568
569
570
571
572
573
574
575
576
577
def rglob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        ("**",) + tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(selector, True)

rmdir() -> None

Source code in cloudpathlib/cloudpath.py 
891
892
893
894
895
896
897
898
899
900
901
902
903
def rmdir(self) -> None:
    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() -> None

Delete an entire directory tree.

Source code in cloudpathlib/cloudpath.py 
1190
1191
1192
1193
1194
1195
1196
def rmtree(self) -> None:
    """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(other_path: Union[str, os.PathLike]) -> bool

Source code in cloudpathlib/cloudpath.py 
905
906
907
def samefile(self, other_path: Union[str, os.PathLike]) -> bool:
    # all cloud paths are absolute and the paths are used for hash
    return self == other_path

stat(follow_symlinks=True)

Source code in cloudpathlib/local/localpath.py 
21
22
23
24
25
26
27
28
def stat(self, follow_symlinks=True):
    try:
        meta = self.client._stat(self)
    except FileNotFoundError:
        raise NoStatError(
            f"No stats available for {self}; it may be a directory or not exist."
        )
    return meta

touch(exist_ok: bool = True, mode: Optional[Any] = None)

Source code in cloudpathlib/local/localpath.py 
30
31
def touch(self, exist_ok: bool = True, mode: Optional[Any] = None):
    self.client._touch(self, exist_ok)
Source code in cloudpathlib/cloudpath.py 
909
910
911
912
913
914
915
def unlink(self, missing_ok: bool = True) -> None:
    # Note: missing_ok defaults to False in pathlib, but changing the default now would be a breaking change.
    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; call rmdir instead of unlink."
        )
    self.client._remove(self, missing_ok)

upload_from(source: Union[str, os.PathLike], force_overwrite_to_cloud: Optional[bool] = None) -> Self

Upload a file or directory to the cloud path.

Source code in cloudpathlib/cloudpath.py 
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
def upload_from(
    self,
    source: Union[str, os.PathLike],
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self:
    """Upload a file or directory to the cloud path."""
    source = Path(source)

    if source.is_dir():
        for p in source.iterdir():
            (self / p.name).upload_from(p, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return self

    else:
        if self.exists() and self.is_dir():
            dst = self / source.name
        else:
            dst = self

        dst._upload_file_to_cloud(source, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return dst

validate(v: str) -> Self classmethod

Used as a Pydantic validator. See https://docs.pydantic.dev/2.0/usage/types/custom/

Source code in cloudpathlib/cloudpath.py 
1687
1688
1689
1690
1691
@classmethod
def validate(cls, v: str) -> Self:
    """Used as a Pydantic validator. See
    https://docs.pydantic.dev/2.0/usage/types/custom/"""
    return cls(v)

walk(top_down: bool = True, on_error: Optional[Callable] = None, follow_symlinks: bool = False, lazy: bool = False) -> Generator[Tuple[Self, List[str], List[str]], None, None]

Walk the directory tree rooted at this path, similar to :meth:pathlib.Path.walk and :func:os.walk.

By default (lazy=False) the entire subtree is listed up front with a single recursive listing, which is the fastest option for a full walk on cloud backends.

Pass lazy=True to defer listing until each directory is visited (one non-recursive listing per directory). This is slower for a full walk, but lets callers prune dirnames in place (when top_down=True) to avoid fetching the contents of skipped subtrees entirely -- which can be dramatically faster and cheaper for sparse traversals.

follow_symlinks is accepted for signature parity with pathlib but has no effect on cloud backends, which do not have symlinks.

Source code in cloudpathlib/cloudpath.py 
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def walk(
    self,
    top_down: bool = True,
    on_error: Optional[Callable] = None,
    follow_symlinks: bool = False,
    lazy: bool = False,
) -> Generator[Tuple[Self, List[str], List[str]], None, None]:
    """Walk the directory tree rooted at this path, similar to
    :meth:`pathlib.Path.walk` and :func:`os.walk`.

    By default (``lazy=False``) the entire subtree is listed up front with a
    single recursive listing, which is the fastest option for a full walk on
    cloud backends.

    Pass ``lazy=True`` to defer listing until each directory is visited (one
    non-recursive listing per directory). This is slower for a full walk,
    but lets callers prune ``dirnames`` in place (when ``top_down=True``) to
    avoid fetching the contents of skipped subtrees entirely -- which can be
    dramatically faster and cheaper for sparse traversals.

    ``follow_symlinks`` is accepted for signature parity with ``pathlib``
    but has no effect on cloud backends, which do not have symlinks.
    """
    if lazy:
        yield from self._walk_lazy(top_down=top_down, on_error=on_error)
        return

    try:
        file_tree = self._build_subtree(recursive=True)  # walking is always recursive
        yield from self._walk_results_from_tree(self, file_tree, top_down=top_down)

    except Exception as e:
        if on_error is not None:
            on_error(e)
        else:
            raise

with_name(name: str) -> Self

Source code in cloudpathlib/cloudpath.py 
1119
1120
def with_name(self, name: str) -> Self:
    return self._dispatch_to_path("with_name", name)

with_segments(*pathsegments) -> Self

Create a new CloudPath with the same client out of the given segments. The first segment will be interpreted as the bucket/container name.

Source code in cloudpathlib/cloudpath.py 
1122
1123
1124
1125
1126
def with_segments(self, *pathsegments) -> Self:
    """Create a new CloudPath with the same client out of the given segments.
    The first segment will be interpreted as the bucket/container name.
    """
    return self._new_cloudpath("/".join(pathsegments))

with_stem(stem: str) -> Self

Source code in cloudpathlib/cloudpath.py 
1112
1113
1114
1115
1116
1117
def with_stem(self, stem: str) -> Self:
    try:
        return self._dispatch_to_path("with_stem", stem)
    except AttributeError:
        # with_stem was only added in python 3.9, so we fallback for compatibility
        return self.with_name(stem + self.suffix)

with_suffix(suffix: str) -> Self

Source code in cloudpathlib/cloudpath.py 
1128
1129
def with_suffix(self, suffix: str) -> Self:
    return self._dispatch_to_path("with_suffix", suffix)

write_bytes(data: bytes) -> int

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

Source code in cloudpathlib/cloudpath.py 
917
918
919
920
921
922
923
924
925
926
def write_bytes(self, data: bytes) -> int:
    """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(data: str, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> int

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.10/Lib/pathlib.py#L1146-L1155

Source code in cloudpathlib/cloudpath.py 
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
def write_text(
    self,
    data: str,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> int:
    """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.10/Lib/pathlib.py#L1146-L1155
    """
    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, newline=newline) as f:
        return f.write(data)

Bases: LocalClient

Replacement for S3Client that uses the local file system. Intended as a monkeypatch substitute when writing tests.

Source code in cloudpathlib/local/implementations/s3.py 
11
12
13
14
15
16
class LocalS3Client(LocalClient):
    """Replacement for S3Client that uses the local file system. Intended as a monkeypatch
    substitute when writing tests.
    """

    _cloud_meta = local_s3_implementation

Attributes

content_type_method = content_type_method instance-attribute

file_cache_mode = file_cache_mode instance-attribute

local_storage_dir: Path property

The local directory where files are stored for this client. This storage directory is the one that simulates the cloud. If no storage directory was provided on instantiating the client, the default storage directory for this client class is used.

Methods:

CloudPath(cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath

Source code in cloudpathlib/client.py 
111
112
def CloudPath(self, cloud_path: Union[str, BoundedCloudPath], *parts: str) -> BoundedCloudPath:
    return self._cloud_meta.path_class(cloud_path, *parts, client=self)  # type: ignore

__init__(*args, local_storage_dir: Optional[Union[str, os.PathLike]] = None, file_cache_mode: Optional[Union[str, FileCacheMode]] = None, local_cache_dir: Optional[Union[str, os.PathLike]] = None, content_type_method: Optional[Callable] = mimetypes.guess_type, **kwargs)

Source code in cloudpathlib/local/localclient.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def __init__(
    self,
    *args,
    local_storage_dir: Optional[Union[str, os.PathLike]] = None,
    file_cache_mode: Optional[Union[str, FileCacheMode]] = None,
    local_cache_dir: Optional[Union[str, os.PathLike]] = None,
    content_type_method: Optional[Callable] = mimetypes.guess_type,
    **kwargs,
):
    self._local_storage_dir = local_storage_dir

    super().__init__(
        local_cache_dir=local_cache_dir,
        content_type_method=content_type_method,
        file_cache_mode=file_cache_mode,
    )

clear_cache()

Clears the contents of the cache folder. Does not remove folder so it can keep being written to.

Source code in cloudpathlib/client.py 
114
115
116
117
118
119
120
121
122
123
def clear_cache(self):
    """Clears the contents of the cache folder.
    Does not remove folder so it can keep being written to.
    """
    if self._local_cache_dir.exists():
        for p in self._local_cache_dir.iterdir():
            if p.is_file():
                p.unlink()
            else:
                shutil.rmtree(p)

get_default_client() -> Client[BoundedCloudPath] classmethod

Get the default client, which the one that is used when instantiating a cloud path instance for this cloud without a client specified.

Source code in cloudpathlib/client.py 
 97
 98
 99
100
101
102
103
104
@classmethod
def get_default_client(cls) -> "Client[BoundedCloudPath]":
    """Get the default client, which the one that is used when instantiating a cloud path
    instance for this cloud without a client specified.
    """
    if cls._default_client is None:
        cls._default_client = cls()
    return cls._default_client

get_default_storage_dir() -> Path classmethod

Return the default storage directory for this client class. This is used if a client is instantiated without a storage directory being explicitly provided. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
46
47
48
49
50
51
52
53
54
55
@classmethod
def get_default_storage_dir(cls) -> Path:
    """Return the default storage directory for this client class. This is used if a client
    is instantiated without a storage directory being explicitly provided. In this usage,
    "storage" refers to the local storage that simulates the cloud.
    """
    if cls._default_storage_temp_dir is None:
        cls._default_storage_temp_dir = TemporaryDirectory()
        _temp_dirs_to_clean.append(cls._default_storage_temp_dir)
    return Path(cls._default_storage_temp_dir.name)

reset_default_storage_dir() -> Path classmethod

Reset the default storage directly. This tears down and recreates the directory used by default for this client class when instantiating a client without explicitly providing a storage directory. In this usage, "storage" refers to the local storage that simulates the cloud.

Source code in cloudpathlib/local/localclient.py 
57
58
59
60
61
62
63
64
65
@classmethod
def reset_default_storage_dir(cls) -> Path:
    """Reset the default storage directly. This tears down and recreates the directory used by
    default for this client class when instantiating a client without explicitly providing
    a storage directory. In this usage, "storage" refers to the local storage that simulates
    the cloud.
    """
    cls._default_storage_temp_dir = None
    return cls.get_default_storage_dir()

set_as_default_client() -> None

Set this client instance as the default one used when instantiating cloud path instances for this cloud without a client specified.

Source code in cloudpathlib/client.py 
106
107
108
109
def set_as_default_client(self) -> None:
    """Set this client instance as the default one used when instantiating cloud path
    instances for this cloud without a client specified."""
    self.__class__._default_client = self

Bases: LocalPath

Replacement for S3Path that uses the local file system. Intended as a monkeypatch substitute when writing tests.

Source code in cloudpathlib/local/implementations/s3.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
class LocalS3Path(LocalPath):
    """Replacement for S3Path that uses the local file system. Intended as a monkeypatch substitute
    when writing tests.
    """

    cloud_prefix: str = "s3://"
    _cloud_meta = local_s3_implementation

    @property
    def drive(self) -> str:
        return self.bucket

    def mkdir(self, parents=False, exist_ok=False, mode: Optional[Any] = None):
        # not possible to make empty directory on s3
        pass

    @property
    def bucket(self) -> str:
        return self._no_prefix.split("/", 1)[0]

    @property
    def key(self) -> str:
        key = self._no_prefix_no_drive

        # key should never have starting slash for
        # use with boto, etc.
        if key.startswith("/"):
            key = key[1:]

        return key

    @property
    def etag(self):
        return self.client._md5(self)

Attributes

anchor: str property

bucket: str property

client: LocalClient instance-attribute

cloud_prefix: str = 's3://' class-attribute instance-attribute

drive: str property

etag property

fspath: str property

key: str property

name: str property

parent: Self property

parents: Tuple[Self, ...] property

parser: Self property

parts: Tuple[str, ...] property

stem: str property

suffix: str property

suffixes: List[str] property

Methods:

__init__(cloud_path: Union[str, Self, CloudPath], *parts: str, client: Optional[Client] = None) -> None

Source code in cloudpathlib/cloudpath.py 
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
def __init__(
    self,
    cloud_path: Union[str, Self, "CloudPath"],
    *parts: str,
    client: Optional["Client"] = None,
) -> None:
    # handle if local file gets opened. must be set at the top of the method in case any code
    # below raises an exception, this prevents __del__ from raising an AttributeError
    self._handle: Optional[IO] = None
    self._client: Optional["Client"] = None

    if parts:
        # ensure first part ends in "/"; (sometimes it is just prefix, sometimes a longer path)
        if not str(cloud_path).endswith("/"):
            cloud_path = str(cloud_path) + "/"

        cloud_path = str(cloud_path) + "/".join(p.strip("/") for p in parts)

    self.is_valid_cloudpath(cloud_path, raise_on_error=True)
    self._cloud_meta.validate_completeness()

    # 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):
            self._client = cloud_path.client
    else:
        self._client = client

    if client is not None and 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."
        )

    # track if local has been written to, if so it may need to be uploaded
    self._dirty = False

absolute() -> Self

Source code in cloudpathlib/cloudpath.py 
1012
1013
def absolute(self) -> Self:
    return self

as_uri() -> str

Source code in cloudpathlib/cloudpath.py 
444
445
def as_uri(self) -> str:
    return str(self)

as_url(presign: bool = False, expire_seconds: int = 60 * 60) -> str

Source code in cloudpathlib/cloudpath.py 
426
427
428
429
430
431
def as_url(self, presign: bool = False, expire_seconds: int = 60 * 60) -> str:
    if presign:
        url = self.client._generate_presigned_url(self, expire_seconds=expire_seconds)
    else:
        url = self.client._get_public_url(self)
    return url

clear_cache()

Removes cache if it exists

Source code in cloudpathlib/cloudpath.py 
1525
1526
1527
1528
1529
1530
1531
def clear_cache(self):
    """Removes cache if it exists"""
    if self._local.exists():
        if self._local.is_file():
            self._local.unlink()
        else:
            shutil.rmtree(self._local)

copy(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

copy(
    target: Self,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy(
    target: Path,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy(
    target: str,
    follow_symlinks=True,
    preserve_metadata=False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self to target folder or file, if self is a file.

Source code in cloudpathlib/cloudpath.py 
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
def copy(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self to target folder or file, if self is a file."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )

copy_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

copy_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

copy_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

copy_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Copy self into target directory, preserving the filename.

Source code in cloudpathlib/cloudpath.py 
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
def copy_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Copy self into target directory, preserving the filename."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=False,
    )
    return cast(Union[Path, Self], result)

copytree(destination, force_overwrite_to_cloud=None, ignore=None) 

copytree(
    destination: Self,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Self

copytree(
    destination: Path,
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Path

copytree(
    destination: Union[str, os.PathLike, Self],
    force_overwrite_to_cloud: Optional[bool] = None,
    ignore: Optional[
        Callable[[str, Iterable[str]], Container[str]]
    ] = None,
) -> Union[Path, CloudPath]

Copy self to a directory, if self is a directory.

Source code in cloudpathlib/cloudpath.py 
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
def copytree(self, destination, force_overwrite_to_cloud=None, ignore=None):
    """Copy self to a directory, if self is a directory."""
    if not self.is_dir():
        raise CloudPathNotADirectoryError(
            f"Origin path {self} must be a directory. To copy a single file use the method copy."
        )

    destination = anypath.to_anypath(destination)

    if destination.exists() and destination.is_file():
        raise CloudPathFileExistsError(
            f"Destination path {destination} of copytree must be a directory."
        )

    contents = list(self.iterdir())

    if ignore is not None:
        ignored_names = ignore(self._no_prefix_no_drive, [x.name for x in contents])
    else:
        ignored_names = set()

    destination.mkdir(parents=True, exist_ok=True)

    for subpath in contents:
        if subpath.name in ignored_names:
            continue
        if subpath.is_file():
            subpath.copy(
                destination / subpath.name, force_overwrite_to_cloud=force_overwrite_to_cloud
            )
        elif subpath.is_dir():
            subpath.copytree(
                destination / (subpath.name + ("" if subpath.name.endswith("/") else "/")),
                force_overwrite_to_cloud=force_overwrite_to_cloud,
                ignore=ignore,
            )

    return destination

download_to(destination: Union[str, os.PathLike]) -> Path

Source code in cloudpathlib/cloudpath.py 
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
def download_to(self, destination: Union[str, os.PathLike]) -> Path:
    destination = Path(destination)

    if not self.exists():
        raise CloudPathNotExistsError(f"Cannot download because path does not exist: {self}")

    if self.is_file():
        if destination.is_dir():
            destination = destination / self.name
        return 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)

        return destination

exists(follow_symlinks=True) -> bool

Source code in cloudpathlib/cloudpath.py 
447
448
def exists(self, follow_symlinks=True) -> bool:
    return self.client._exists(self)

from_uri(uri: str) -> Self classmethod

Source code in cloudpathlib/cloudpath.py 
460
461
462
@classmethod
def from_uri(cls, uri: str) -> Self:
    return cls(uri)

full_match(pattern: str, case_sensitive: Optional[bool] = None) -> bool

Source code in cloudpathlib/cloudpath.py 
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
def full_match(self, pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    if sys.version_info < (3, 13):
        raise NotImplementedError("full_match requires Python 3.13 or higher")

    # strip scheme from start of pattern before testing
    if pattern.startswith(self.anchor + self.drive):
        pattern = pattern[len(self.anchor + self.drive) :]
    elif pattern.startswith(self.anchor):
        # for http paths, keep leading slash
        pattern = pattern[len(self.anchor) - 1 :]

    # remove drive, which is kept on normal dispatch to pathlib
    return PurePosixPath(self._no_prefix_no_drive).full_match(  # type: ignore[attr-defined]
        pattern, case_sensitive=case_sensitive
    )

glob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]

Source code in cloudpathlib/cloudpath.py 
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
def glob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(
        selector,
        "/" in pattern
        or "**"
        in pattern,  # recursive listing needed if explicit ** or any sub folder in pattern
    )

info() -> CloudPathInfo

Return a CloudPathInfo object for this path.

Source code in cloudpathlib/cloudpath.py 
1163
1164
1165
def info(self) -> "CloudPathInfo":
    """Return a CloudPathInfo object for this path."""
    return CloudPathInfo(self)

is_absolute() -> bool

Source code in cloudpathlib/cloudpath.py 
1015
1016
def is_absolute(self) -> bool:
    return True

is_dir(follow_symlinks=True) -> bool

Source code in cloudpathlib/local/localpath.py 
15
16
def is_dir(self, follow_symlinks=True) -> bool:
    return self.client._is_dir(self, follow_symlinks=follow_symlinks)

is_file(follow_symlinks=True) -> bool

Source code in cloudpathlib/local/localpath.py 
18
19
def is_file(self, follow_symlinks=True) -> bool:
    return self.client._is_file(self, follow_symlinks=follow_symlinks)

is_junction()

Source code in cloudpathlib/cloudpath.py 
959
960
def is_junction(self):
    return False  # only windows paths can be junctions, not cloudpaths

is_relative_to(other: Self) -> bool

Source code in cloudpathlib/cloudpath.py 
1038
1039
1040
1041
1042
1043
def is_relative_to(self, other: Self) -> bool:
    try:
        self.relative_to(other)
        return True
    except ValueError:
        return False

is_valid_cloudpath(path: Union[str, CloudPath], raise_on_error: bool = False) -> Union[bool, TypeGuard[Self]] classmethod 

is_valid_cloudpath(
    path: CloudPath, raise_on_error: bool = ...
) -> TypeGuard[Self]

is_valid_cloudpath(
    path: str, raise_on_error: bool = ...
) -> bool
Source code in cloudpathlib/cloudpath.py 
332
333
334
335
336
337
338
339
340
341
342
343
@classmethod
def is_valid_cloudpath(
    cls, path: Union[str, "CloudPath"], raise_on_error: bool = False
) -> Union[bool, TypeGuard[Self]]:
    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() -> Generator[Self, None, None]

Source code in cloudpathlib/cloudpath.py 
579
580
581
582
def iterdir(self) -> Generator[Self, None, None]:
    for f, _ in self.client._list_dir(self, recursive=False):
        if f != self:  # iterdir does not include itself in pathlib
            yield f

joinpath(*pathsegments: Union[str, os.PathLike]) -> Self

Source code in cloudpathlib/cloudpath.py 
1009
1010
def joinpath(self, *pathsegments: Union[str, os.PathLike]) -> Self:
    return self._dispatch_to_path("joinpath", *pathsegments)

match(path_pattern: str, case_sensitive: Optional[bool] = None) -> bool

Source code in cloudpathlib/cloudpath.py 
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
def match(self, path_pattern: str, case_sensitive: Optional[bool] = None) -> bool:
    # 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 + "/") :]

    kwargs = dict(case_sensitive=case_sensitive)

    if sys.version_info < (3, 12):
        kwargs.pop("case_sensitive")

    return self._dispatch_to_path("match", path_pattern, **kwargs)

mkdir(parents=False, exist_ok=False, mode: Optional[Any] = None)

Source code in cloudpathlib/local/implementations/s3.py 
34
35
36
def mkdir(self, parents=False, exist_ok=False, mode: Optional[Any] = None):
    # not possible to make empty directory on s3
    pass

move(target: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

move(
    target: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move(
    target: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move(
    target: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self to target location, removing the source.

Source code in cloudpathlib/cloudpath.py 
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
def move(
    self,
    target: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self to target location, removing the source."""
    return self._copy(
        target,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )

move_into(target_dir: Union[str, os.PathLike, Self], follow_symlinks: bool = True, preserve_metadata: bool = False, force_overwrite_to_cloud: Optional[bool] = None) -> Union[Path, Self] 

move_into(
    target_dir: Self,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self

move_into(
    target_dir: Path,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Path

move_into(
    target_dir: str,
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, CloudPath]

Move self into target directory, preserving the filename and removing the source.

Source code in cloudpathlib/cloudpath.py 
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
def move_into(
    self,
    target_dir: Union[str, os.PathLike, Self],
    follow_symlinks: bool = True,
    preserve_metadata: bool = False,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Union[Path, Self]:
    """Move self into target directory, preserving the filename and removing the source."""
    target_path = anypath.to_anypath(target_dir) / self.name

    result = self._copy(
        target_path,
        follow_symlinks=follow_symlinks,
        preserve_metadata=preserve_metadata,
        force_overwrite_to_cloud=force_overwrite_to_cloud,
        remove_src=True,
    )
    return cast(Union[Path, Self], result)

open(mode: str = 'r', buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, force_overwrite_from_cloud: Optional[bool] = None, force_overwrite_to_cloud: Optional[bool] = None) -> IO[Any] 

open(
    mode: OpenTextMode = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> TextIOWrapper

open(
    mode: OpenBinaryMode,
    buffering: Literal[0],
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> FileIO

open(
    mode: OpenBinaryModeUpdating,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedRandom

open(
    mode: OpenBinaryModeWriting,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedWriter

open(
    mode: OpenBinaryModeReading,
    buffering: Literal[-1, 1] = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BufferedReader

open(
    mode: OpenBinaryMode,
    buffering: int = -1,
    encoding: None = None,
    errors: None = None,
    newline: None = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> BinaryIO

open(
    mode: str,
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,
    force_overwrite_to_cloud: Optional[bool] = None,
) -> IO[Any]
Source code in cloudpathlib/cloudpath.py 
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
def open(
    self,
    mode: str = "r",
    buffering: int = -1,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
    force_overwrite_from_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
    force_overwrite_to_cloud: Optional[bool] = None,  # extra kwarg not in pathlib
) -> "IO[Any]":
    # if trying to call open on a directory that exists
    exists_on_cloud = self.exists()

    if exists_on_cloud and not self.is_file():
        raise CloudPathIsADirectoryError(
            f"Cannot open directory, only files. Tried to open ({self})"
        )

    if not exists_on_cloud and any(m in mode for m in ("r", "a")):
        raise CloudPathFileNotFoundError(
            f"File opened for read or append, but it does not exist on cloud: {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.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
        wrapped_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_upload(*args, **kwargs) -> None:
            wrapped_close(*args, **kwargs)

            # we should be idempotent and not upload again if
            # we already ran our close method patch
            if not self._dirty:
                return

            # 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)
            self._dirty = False

        buffer.close = _patched_close_upload  # type: ignore

        # 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

    # if we don't want any cache around, remove the cache
    # as soon as the file is closed
    if self.client.file_cache_mode == FileCacheMode.close_file:
        # this may be _patched_close_upload, in which case we need to
        # make sure to call that first so the file gets uploaded
        wrapped_close_for_cache = buffer.close

        def _patched_close_empty_cache(*args, **kwargs):
            wrapped_close_for_cache(*args, **kwargs)

            # remove local file as last step on closing
            self.clear_cache()

        buffer.close = _patched_close_empty_cache  # type: ignore

    return buffer

read_bytes() -> bytes

Source code in cloudpathlib/cloudpath.py 
946
947
948
def read_bytes(self) -> bytes:
    with self.open(mode="rb") as f:
        return f.read()

read_text(encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> str

Source code in cloudpathlib/cloudpath.py 
950
951
952
953
954
955
956
957
def read_text(
    self,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> str:
    with self.open(mode="r", encoding=encoding, errors=errors, newline=newline) as f:
        return f.read()

relative_to(other: Self, walk_up: bool = False) -> PurePosixPath

Source code in cloudpathlib/cloudpath.py 
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
def relative_to(self, other: Self, walk_up: bool = False) -> PurePosixPath:
    # We don't dispatch regularly since this never returns a cloud path (since it is relative, and cloud paths are
    # absolute)
    if not isinstance(other, CloudPath):
        raise ValueError(f"{self} is a cloud path, but {other} is not")
    if self.anchor != other.anchor:
        raise ValueError(
            f"{self} is a {self.anchor} path, but {other} is a {other.anchor} path"
        )

    kwargs = dict(walk_up=walk_up)

    if sys.version_info < (3, 12):
        kwargs.pop("walk_up")

    return self._path.relative_to(other._path, **kwargs)  # type: ignore[call-arg]

rename(target: Self) -> Self

Source code in cloudpathlib/cloudpath.py 
886
887
888
889
def rename(self, target: Self) -> Self:
    # for cloud services replace == rename since we don't just rename,
    # we actually move files
    return self.replace(target)

replace(target: Self) -> Self

Source code in cloudpathlib/cloudpath.py 
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
def replace(self, target: Self) -> Self:
    if type(self) is not type(target):
        raise TypeError(
            f"The target based to rename must be an instantiated class of type: {type(self)}"
        )

    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; rename/replace the files recursively."
        )

    if target == self:
        # Request is to replace/rename this with the same path - nothing to do
        return self

    if target.exists():
        target.unlink()

    self.client._move_file(self, target)
    return target

resolve(strict: bool = False) -> Self

Source code in cloudpathlib/cloudpath.py 
1018
1019
def resolve(self, strict: bool = False) -> Self:
    return self

rglob(pattern: Union[str, os.PathLike], case_sensitive: Optional[bool] = None, recurse_symlinks: bool = True) -> Generator[Self, None, None]

Source code in cloudpathlib/cloudpath.py 
564
565
566
567
568
569
570
571
572
573
574
575
576
577
def rglob(
    self,
    pattern: Union[str, os.PathLike],
    case_sensitive: Optional[bool] = None,
    recurse_symlinks: bool = True,
) -> Generator[Self, None, None]:
    pattern = self._glob_checks(pattern)

    pattern_parts = PurePosixPath(pattern).parts
    selector = _make_selector(
        ("**",) + tuple(pattern_parts), _posix_flavour, case_sensitive=case_sensitive
    )

    yield from self._glob(selector, True)

rmdir() -> None

Source code in cloudpathlib/cloudpath.py 
891
892
893
894
895
896
897
898
899
900
901
902
903
def rmdir(self) -> None:
    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() -> None

Delete an entire directory tree.

Source code in cloudpathlib/cloudpath.py 
1190
1191
1192
1193
1194
1195
1196
def rmtree(self) -> None:
    """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(other_path: Union[str, os.PathLike]) -> bool

Source code in cloudpathlib/cloudpath.py 
905
906
907
def samefile(self, other_path: Union[str, os.PathLike]) -> bool:
    # all cloud paths are absolute and the paths are used for hash
    return self == other_path

stat(follow_symlinks=True)

Source code in cloudpathlib/local/localpath.py 
21
22
23
24
25
26
27
28
def stat(self, follow_symlinks=True):
    try:
        meta = self.client._stat(self)
    except FileNotFoundError:
        raise NoStatError(
            f"No stats available for {self}; it may be a directory or not exist."
        )
    return meta

touch(exist_ok: bool = True, mode: Optional[Any] = None)

Source code in cloudpathlib/local/localpath.py 
30
31
def touch(self, exist_ok: bool = True, mode: Optional[Any] = None):
    self.client._touch(self, exist_ok)
Source code in cloudpathlib/cloudpath.py 
909
910
911
912
913
914
915
def unlink(self, missing_ok: bool = True) -> None:
    # Note: missing_ok defaults to False in pathlib, but changing the default now would be a breaking change.
    if self.is_dir():
        raise CloudPathIsADirectoryError(
            f"Path {self} is a directory; call rmdir instead of unlink."
        )
    self.client._remove(self, missing_ok)

upload_from(source: Union[str, os.PathLike], force_overwrite_to_cloud: Optional[bool] = None) -> Self

Upload a file or directory to the cloud path.

Source code in cloudpathlib/cloudpath.py 
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
def upload_from(
    self,
    source: Union[str, os.PathLike],
    force_overwrite_to_cloud: Optional[bool] = None,
) -> Self:
    """Upload a file or directory to the cloud path."""
    source = Path(source)

    if source.is_dir():
        for p in source.iterdir():
            (self / p.name).upload_from(p, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return self

    else:
        if self.exists() and self.is_dir():
            dst = self / source.name
        else:
            dst = self

        dst._upload_file_to_cloud(source, force_overwrite_to_cloud=force_overwrite_to_cloud)

        return dst

validate(v: str) -> Self classmethod

Used as a Pydantic validator. See https://docs.pydantic.dev/2.0/usage/types/custom/

Source code in cloudpathlib/cloudpath.py 
1687
1688
1689
1690
1691
@classmethod
def validate(cls, v: str) -> Self:
    """Used as a Pydantic validator. See
    https://docs.pydantic.dev/2.0/usage/types/custom/"""
    return cls(v)

walk(top_down: bool = True, on_error: Optional[Callable] = None, follow_symlinks: bool = False, lazy: bool = False) -> Generator[Tuple[Self, List[str], List[str]], None, None]

Walk the directory tree rooted at this path, similar to :meth:pathlib.Path.walk and :func:os.walk.

By default (lazy=False) the entire subtree is listed up front with a single recursive listing, which is the fastest option for a full walk on cloud backends.

Pass lazy=True to defer listing until each directory is visited (one non-recursive listing per directory). This is slower for a full walk, but lets callers prune dirnames in place (when top_down=True) to avoid fetching the contents of skipped subtrees entirely -- which can be dramatically faster and cheaper for sparse traversals.

follow_symlinks is accepted for signature parity with pathlib but has no effect on cloud backends, which do not have symlinks.

Source code in cloudpathlib/cloudpath.py 
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def walk(
    self,
    top_down: bool = True,
    on_error: Optional[Callable] = None,
    follow_symlinks: bool = False,
    lazy: bool = False,
) -> Generator[Tuple[Self, List[str], List[str]], None, None]:
    """Walk the directory tree rooted at this path, similar to
    :meth:`pathlib.Path.walk` and :func:`os.walk`.

    By default (``lazy=False``) the entire subtree is listed up front with a
    single recursive listing, which is the fastest option for a full walk on
    cloud backends.

    Pass ``lazy=True`` to defer listing until each directory is visited (one
    non-recursive listing per directory). This is slower for a full walk,
    but lets callers prune ``dirnames`` in place (when ``top_down=True``) to
    avoid fetching the contents of skipped subtrees entirely -- which can be
    dramatically faster and cheaper for sparse traversals.

    ``follow_symlinks`` is accepted for signature parity with ``pathlib``
    but has no effect on cloud backends, which do not have symlinks.
    """
    if lazy:
        yield from self._walk_lazy(top_down=top_down, on_error=on_error)
        return

    try:
        file_tree = self._build_subtree(recursive=True)  # walking is always recursive
        yield from self._walk_results_from_tree(self, file_tree, top_down=top_down)

    except Exception as e:
        if on_error is not None:
            on_error(e)
        else:
            raise

with_name(name: str) -> Self

Source code in cloudpathlib/cloudpath.py 
1119
1120
def with_name(self, name: str) -> Self:
    return self._dispatch_to_path("with_name", name)

with_segments(*pathsegments) -> Self

Create a new CloudPath with the same client out of the given segments. The first segment will be interpreted as the bucket/container name.

Source code in cloudpathlib/cloudpath.py 
1122
1123
1124
1125
1126
def with_segments(self, *pathsegments) -> Self:
    """Create a new CloudPath with the same client out of the given segments.
    The first segment will be interpreted as the bucket/container name.
    """
    return self._new_cloudpath("/".join(pathsegments))

with_stem(stem: str) -> Self

Source code in cloudpathlib/cloudpath.py 
1112
1113
1114
1115
1116
1117
def with_stem(self, stem: str) -> Self:
    try:
        return self._dispatch_to_path("with_stem", stem)
    except AttributeError:
        # with_stem was only added in python 3.9, so we fallback for compatibility
        return self.with_name(stem + self.suffix)

with_suffix(suffix: str) -> Self

Source code in cloudpathlib/cloudpath.py 
1128
1129
def with_suffix(self, suffix: str) -> Self:
    return self._dispatch_to_path("with_suffix", suffix)

write_bytes(data: bytes) -> int

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

Source code in cloudpathlib/cloudpath.py 
917
918
919
920
921
922
923
924
925
926
def write_bytes(self, data: bytes) -> int:
    """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(data: str, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) -> int

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.10/Lib/pathlib.py#L1146-L1155

Source code in cloudpathlib/cloudpath.py 
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
def write_text(
    self,
    data: str,
    encoding: Optional[str] = None,
    errors: Optional[str] = None,
    newline: Optional[str] = None,
) -> int:
    """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.10/Lib/pathlib.py#L1146-L1155
    """
    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, newline=newline) as f:
        return f.write(data)