# cloud-storage-mocker
Mocker library of
[Google Cloud Storage Python client](https://github.com/googleapis/python-storage)
with local filesystem mounting.
## Install
For package users:
```shell
pip install cloud-storage-mocker
```
For package developers:
```shell
git clone git@github.com:CroudTech/cloud-storage-mocker
cd cloud-storage-mocker
python -m venv venv
source venv/bin/activate
pip install -e '.[dev]'
```
## How the package works
### Basic usage
This library provides `patch` context manager, which replaces following classes on the
[`google-cloud-storage`](https://github.com/googleapis/python-storage) package:
- `Client`
- `Bucket`
- `Blob`
`patch` takes a list of `Mount` objects, which represent mappings between bucket names
and directories on the local filesystem.
Each `Mount` has Boolean configs `readable` and `writable` to control read/write
permissions to the mounted buckets.
A canonical use-case of this package is writing unit tests to check the behavior of the
code that works with Google Cloud Storage:
```python
import pathlib
import google.cloud.storage # type: ignore[import]
from ct_cloud_storage_mocker import BlobMetadata, Mount
from ct_cloud_storage_mocker import patch as gcs_patch
def test_something(tmp_path: pathlib.Path) -> None:
# Creates two temporary directories for readable/writable buckets.
src_dir = tmp_path / "src"
dest_dir = tmp_path / "dest"
src_dir.mkdir()
dest_dir.mkdir()
# A sample file on the readable bucket.
(src_dir / "hello.txt").write_text("Hello.")
# Optionally, object metadata can also be specified by the file beside the
# content, suffixed by ".__metadata__".
(src_dir / "hello.txt.__metadata__").write_text(
BlobMetadata(content_type="text/plain").dump_json()
)
# Mounts directories. Empty list is allowed if no actual access is required.
with gcs_patch(
[
Mount("readable", src_dir, readable=True),
Mount("writable", dest_dir, writable=True),
],
):
client = google.cloud.storage.Client()
# Reads a blob.
blob = client.bucket("readable").blob("hello.txt")
assert blob.download_as_text() == "Hello."
# Metadata is available after downloading the content.
assert blob.content_type == "text/plain"
# Writes a blob.
blob = client.bucket("writable").blob("world.txt")
blob.upload_from_string("World.")
# Checks if the file is written appropriately.
assert (dest_dir / "world.txt").read_text() == "World."
```
## Patched methods/properties
Methods listed below have specialized behavior to mount the local filesystem.
Other methods are mapped to `MagicMock`.
```
Client()
Client.bucket()
Bucket()
Bucket.blob()
Blob()
# Blob properties (download only)
Blob.cache_control
Blob.content_disposition
Blob.content_encoding
Blob.content_language
Blob.content_type
Blob.download_to_file()
Blob.download_to_filename()
Blob.download_as_bytes()
Blob.download_as_string()
Blob.download_as_text()
Blob.upload_from_file()
Blob.upload_from_filename()
Blob.upload_from_string()
```
## Caution
This library is basically provided for writing unit tests.
DO NOT use this library on any code on the production.
Raw data
{
"_id": null,
"home_page": null,
"name": "ct-cloud-storage-mocker",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.8",
"maintainer_email": null,
"keywords": "cloud storage, gcloud, google, google cloud, storage",
"author": "Jim Robinson",
"author_email": "jim.robinson@croud.com",
"download_url": "https://files.pythonhosted.org/packages/ad/de/3a4db994a8694c39b29a9677bfa1ac2692c253e1731ad3487906c8c765dc/ct_cloud_storage_mocker-0.1.5.tar.gz",
"platform": null,
"description": "# cloud-storage-mocker\n\nMocker library of\n[Google Cloud Storage Python client](https://github.com/googleapis/python-storage)\nwith local filesystem mounting.\n\n\n## Install\n\nFor package users:\n\n```shell\npip install cloud-storage-mocker\n```\n\nFor package developers:\n\n```shell\ngit clone git@github.com:CroudTech/cloud-storage-mocker\ncd cloud-storage-mocker\npython -m venv venv\nsource venv/bin/activate\npip install -e '.[dev]'\n```\n\n\n## How the package works\n\n\n### Basic usage\n\nThis library provides `patch` context manager, which replaces following classes on the\n[`google-cloud-storage`](https://github.com/googleapis/python-storage) package:\n\n- `Client`\n- `Bucket`\n- `Blob`\n\n`patch` takes a list of `Mount` objects, which represent mappings between bucket names\nand directories on the local filesystem.\nEach `Mount` has Boolean configs `readable` and `writable` to control read/write\npermissions to the mounted buckets.\n\nA canonical use-case of this package is writing unit tests to check the behavior of the\ncode that works with Google Cloud Storage:\n\n```python\nimport pathlib\n\nimport google.cloud.storage # type: ignore[import]\n\nfrom ct_cloud_storage_mocker import BlobMetadata, Mount\nfrom ct_cloud_storage_mocker import patch as gcs_patch\n\n\ndef test_something(tmp_path: pathlib.Path) -> None:\n # Creates two temporary directories for readable/writable buckets.\n src_dir = tmp_path / \"src\"\n dest_dir = tmp_path / \"dest\"\n src_dir.mkdir()\n dest_dir.mkdir()\n\n # A sample file on the readable bucket.\n (src_dir / \"hello.txt\").write_text(\"Hello.\")\n # Optionally, object metadata can also be specified by the file beside the\n # content, suffixed by \".__metadata__\".\n (src_dir / \"hello.txt.__metadata__\").write_text(\n BlobMetadata(content_type=\"text/plain\").dump_json()\n )\n\n # Mounts directories. Empty list is allowed if no actual access is required.\n with gcs_patch(\n [\n Mount(\"readable\", src_dir, readable=True),\n Mount(\"writable\", dest_dir, writable=True),\n ],\n ):\n client = google.cloud.storage.Client()\n\n # Reads a blob.\n blob = client.bucket(\"readable\").blob(\"hello.txt\")\n assert blob.download_as_text() == \"Hello.\"\n # Metadata is available after downloading the content.\n assert blob.content_type == \"text/plain\"\n\n # Writes a blob.\n blob = client.bucket(\"writable\").blob(\"world.txt\")\n blob.upload_from_string(\"World.\")\n\n # Checks if the file is written appropriately.\n assert (dest_dir / \"world.txt\").read_text() == \"World.\"\n```\n\n\n## Patched methods/properties\n\nMethods listed below have specialized behavior to mount the local filesystem.\n\nOther methods are mapped to `MagicMock`.\n\n```\nClient()\n\nClient.bucket()\n\nBucket()\n\nBucket.blob()\n\nBlob()\n\n# Blob properties (download only)\nBlob.cache_control\nBlob.content_disposition\nBlob.content_encoding\nBlob.content_language\nBlob.content_type\n\nBlob.download_to_file()\nBlob.download_to_filename()\nBlob.download_as_bytes()\nBlob.download_as_string()\nBlob.download_as_text()\nBlob.upload_from_file()\nBlob.upload_from_filename()\nBlob.upload_from_string()\n```\n\n\n## Caution\n\nThis library is basically provided for writing unit tests.\nDO NOT use this library on any code on the production.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Mocker library of Google Cloud Storage with local filesystem mounting. Update for python3.13 compatibility",
"version": "0.1.5",
"project_urls": {
"Bug Tracker": "https://github.com/CroudTech/cloud-storage-mocker/issues",
"Homepage": "https://github.com/CroudTech/cloud-storage-mocker"
},
"split_keywords": [
"cloud storage",
" gcloud",
" google",
" google cloud",
" storage"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f76dc3e384966cdd677d37414c177e6a3096862c019ff6a32d48f87276cc0bee",
"md5": "1f0a58a61a01bfb0ef6c7afeeffd4df9",
"sha256": "8f0e517740b56aa3cc8835ff3c0c103c2f2a91849c232ce1ec2f8d940dc01531"
},
"downloads": -1,
"filename": "ct_cloud_storage_mocker-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1f0a58a61a01bfb0ef6c7afeeffd4df9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.8",
"size": 9510,
"upload_time": "2025-09-04T15:20:01",
"upload_time_iso_8601": "2025-09-04T15:20:01.332786Z",
"url": "https://files.pythonhosted.org/packages/f7/6d/c3e384966cdd677d37414c177e6a3096862c019ff6a32d48f87276cc0bee/ct_cloud_storage_mocker-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "adde3a4db994a8694c39b29a9677bfa1ac2692c253e1731ad3487906c8c765dc",
"md5": "2d87ba2208c139c02b843e631456d426",
"sha256": "50a822b624b378901e9c28d7a0b15de0a76abcd8163db4aab322781b828a2cfb"
},
"downloads": -1,
"filename": "ct_cloud_storage_mocker-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "2d87ba2208c139c02b843e631456d426",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.8",
"size": 8271,
"upload_time": "2025-09-04T15:20:02",
"upload_time_iso_8601": "2025-09-04T15:20:02.446154Z",
"url": "https://files.pythonhosted.org/packages/ad/de/3a4db994a8694c39b29a9677bfa1ac2692c253e1731ad3487906c8c765dc/ct_cloud_storage_mocker-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-04 15:20:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CroudTech",
"github_project": "cloud-storage-mocker",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ct-cloud-storage-mocker"
}
JSON
