From 7e96e663de26d007f43c1fa33198f6992a4039d3 Mon Sep 17 00:00:00 2001 From: Rick McGeer Date: Mon, 18 Nov 2024 07:56:44 -0800 Subject: [PATCH] Added note about refresh and POSIX behavior (#648) Co-authored-by: Martin Durant --- gcsfs/core.py | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/gcsfs/core.py b/gcsfs/core.py index 73dbcebd..6ae4c60c 100644 --- a/gcsfs/core.py +++ b/gcsfs/core.py @@ -210,7 +210,14 @@ class GCSFileSystem(asyn.AsyncFileSystem): GCSFileSystem maintains a per-implied-directory cache of object listings and fulfills all object information and listing requests from cache. This implied, for example, that objects created via other processes *will not* be visible to the GCSFileSystem until the cache - refreshed. Calls to GCSFileSystem.open and calls to GCSFile are not effected by this cache. + refreshed. Calls to GCSFileSystem.open and calls to GCSFile are not affected by this cache. + + Note that directory listings are cached by default, because fetching those listings can be expensive. This is + contrary to local filesystem behaviour. The cache will be cleared if writing from this instance, but it can + become stale and return incorrect results if the storage is written to from another process/machine. + If you anticipate this possibility, you can set the use_listings_cache and listings_expiry_time arguments + to configure the caching, call `.invalidate_cache()` when required, or pass `refresh=True` to the + various listing methods. In the default case the cache is never expired. This may be controlled via the ``cache_timeout`` GCSFileSystem parameter or via explicit calls to ``GCSFileSystem.invalidate_cache``.