docs: be more verbose in s3cc docstrings

CHANGELOG

@@ -1,3 +1,5 @@
+0.7.1
+ - docs: be more verbose in s3cc docstrings
 0.7.0
  - feat: implement `s3.create_presigned_upload_url` for creating presigned
    upload URLs that DCOR-Aid can use to upload resources directly to S3

dcor_shared/s3cc.py

@@ -26,7 +26,11 @@ def create_presigned_url(
         artifact: Literal["condensed", "preview", "resource"] = "resource",
         expiration: int = 3600,
         filename: str = None):
-    """Create a presigned URL for a given artifact of a CKAN resource"""
+    """Create a presigned URL for a given artifact of a CKAN resource
+
+    The resource with the identifier `resource_id` must exist in the
+    CKAN database.
+    """
     bucket_name, object_name = get_s3_bucket_object_for_artifact(
         resource_id=resource_id, artifact=artifact)
     return s3.create_presigned_url(bucket_name=bucket_name,
@@ -42,6 +46,9 @@ def get_s3_bucket_object_for_artifact(
 
     The value of artifact can be either "condensed", "preview", or "resource"
     (those are the keys under which the individual objects are stored in S3).
+
+    The resource with the identifier `resource_id` must exist in the
+    CKAN database.
     """
     bucket_name = get_s3_bucket_name_for_resource(resource_id=resource_id)
     rid = resource_id
@@ -54,6 +61,9 @@ def get_s3_bucket_name_for_resource(resource_id):
 
     The bucket name is determined by the ID of the organization
     which the dataset containing the resource belongs to.
+
+    The resource with the identifier `resource_id` must exist in the
+    CKAN database.
     """
     import ckan.logic
     res_dict = ckan.logic.get_action('resource_show')(
@@ -69,7 +79,11 @@ def get_s3_bucket_name_for_resource(resource_id):
 
 
 def get_s3_dc_handle(resource_id):
-    """Return an instance of :class:`RTDC_S3`"""
+    """Return an instance of :class:`RTDC_S3`
+
+    The resource with the identifier `resource_id` must exist in the
+    CKAN database.
+    """
     s3_url = get_s3_url_for_artifact(resource_id)
     ds = fmt_s3.RTDC_S3(
         url=s3_url,
@@ -88,6 +102,9 @@ def get_s3_url_for_artifact(
 
     The value of artifact can be either "condensed", "preview", or "resource"
     (those are the keys under which the individual objects are stored in S3).
+
+    The resource with the identifier `resource_id` must exist in the
+    CKAN database.
     """
     s3_endpoint = get_ckan_config_option("dcor_object_store.endpoint_url")
     bucket_name, object_name = get_s3_bucket_object_for_artifact(
@@ -97,7 +114,11 @@ def get_s3_url_for_artifact(
 
 def make_resource_public(resource_id: str,
                          missing_ok: bool = True):
-    """Make a resource, including all its artifacts, public"""
+    """Make a resource, including all its artifacts, public
+
+    The resource with the identifier `resource_id` must exist in the
+    CKAN database.
+    """
     for artifact in ["condensed", "preview", "resource"]:
         bucket_name, object_name = get_s3_bucket_object_for_artifact(
             resource_id=resource_id, artifact=artifact)
@@ -109,6 +130,11 @@ def make_resource_public(resource_id: str,
 def object_exists(
         resource_id: str,
         artifact: Literal["condensed", "preview", "resource"] = "resource"):
+    """Check whether an object is available on S3
+
+    The resource with the identifier `resource_id` must exist in the
+    CKAN database.
+    """
     bucket_name, object_name = get_s3_bucket_object_for_artifact(
         resource_id=resource_id, artifact=artifact)
     return s3.object_exists(bucket_name=bucket_name, object_name=object_name)