Local cloud-alike file system storage

from fake import FAKER
from fakepy.cloudpathlib_storage.cloud import LocalFileSystemStorage

STORAGE = LocalFileSystemStorage(
    bucket_name="bucket_name",
    root_path="tmp",  # Optional
    rel_path="sub-tmp",  # Optional
)

pdf_file = FAKER.pdf_file(storage=STORAGE)

STORAGE.exists(pdf_file)

LocalFileSystemStorage uses pathlib.Path, since cloudpathlib has no file:// backend. Files are stored under local_storage_dir (defaults to the system temporary directory). CloudpathlibFileSystemStorage is an alias. abspath() returns a standard absolute file:/// URI.

AWS S3

from fake import FAKER
from fakepy.cloudpathlib_storage.aws_s3 import AWSS3Storage

STORAGE = AWSS3Storage(
    bucket_name="bucket_name",
    root_path="tmp",  # Optional
    rel_path="sub-tmp",  # Optional
    # Credentials are optional too. If your AWS credentials are properly
    # set in the ~/.aws/credentials, you don't need to send them
    # explicitly.
    credentials={
        "key_id": "YOUR KEY ID",
        "key_secret": "YOUR KEY SECRET"
    },
)

pdf_file = FAKER.pdf_file(storage=STORAGE)

STORAGE.exists(pdf_file)

Additional S3Client options (session tokens, profiles, custom endpoints, cache settings, etc.) go in client_kwargs.

Google Cloud Storage

from fake import FAKER
from fakepy.cloudpathlib_storage.google_cloud_storage import (
    GoogleCloudStorage,
)

STORAGE = GoogleCloudStorage(
    bucket_name="bucket_name",
    root_path="tmp",  # Optional
    rel_path="sub-tmp",  # Optional
    # Optional. Omit to use application default credentials.
    credentials={"json_file_path": "/path/to/service-account.json"},
)

pdf_file = FAKER.pdf_file(storage=STORAGE)

STORAGE.exists(pdf_file)

json_file_path maps to GSClient’s application_credentials.

Azure Cloud Storage

from fake import FAKER
from fakepy.cloudpathlib_storage.azure_cloud_storage import (
    AzureCloudStorage,
)

STORAGE = AzureCloudStorage(
    bucket_name="bucket_name",
    root_path="tmp",  # Optional
    rel_path="sub-tmp",  # Optional
    credentials={"connection_string": "YOUR CONNECTION STRING"},
)

pdf_file = FAKER.pdf_file(storage=STORAGE)

STORAGE.exists(pdf_file)

Azure paths use cloudpathlib’s az:// scheme. Other AzureBlobClient options may be passed through client_kwargs.

Shared API and path semantics

from fakepy.cloudpathlib_storage.cloud import LocalFileSystemStorage

storage = LocalFileSystemStorage(bucket_name="bucket_name")

filename = storage.generate_filename(extension="txt", prefix="sample_")
storage.write_text(filename, "Lorem ipsum", encoding="utf-8")
storage.write_bytes(filename, b"Lorem ipsum")
assert storage.exists(filename)
relative_name = storage.relpath(filename)
absolute_uri = storage.abspath(filename)
storage.unlink(filename)

• Generated paths are bucket/root_path/rel_path/basename.extension.

• String relative filenames resolve against bucket/root_path (not bucket/root_path/rel_path). Use relpath(filename) to obtain a round-trip relative name.

• None or empty root_path/rel_path omit that component.

• Path objects, their string representations and provider URIs are accepted.

• write_text returns characters written; write_bytes returns bytes written.

• An empty extension raises ValueError.

• Unlinking a missing file raises FileNotFoundError, consistently across providers.

Offline cloud tests

Pass a cloudpathlib local client to test without touching real clouds:

from cloudpathlib.local import LocalS3Client
from fakepy.cloudpathlib_storage.aws_s3 import AWSS3Storage

client = LocalS3Client(local_storage_dir="/tmp/mock-cloud")
storage = AWSS3Storage("example", client=client)
filename = storage.generate_filename("txt", basename="sample")
storage.write_text(filename, "offline")
assert filename.read_text() == "offline"
storage.unlink(filename)

LocalGSClient and LocalAzureBlobClient work the same way. The latter requires a non-empty dummy connection_string.