Release 0.3.0 (#45)

CHANGELOG.md

@@ -1,5 +1,12 @@
 # SAMS Changelog
 
+## [0.3.0] 2021-09-06
+### Features
+- [SDESK-6144] New endpoints for image renditions (#44)
+
+### Improvements
+- chore(docs): Update docs
+
 ## [0.2.4] 2021-06-23
 ### Improvements
 - chore(docs): Update docs (#2113664)

docs/changelog.rst

@@ -2,6 +2,25 @@
 SAMS Changelog
 ==============
 
+0.3.0 - 2021-09-06
+==================
+
+**Features**
+
+- [SDESK-6144] New endpoints for image renditions (#44)
+
+0.2.4 - 2021-06-23
+==================
+
+**Improvements**
+
+- chore(docs): Update docs (#2113664)
+
+**Fixes**
+
+- fix(docs): Fix documentation for StorageProviders (#e07d925)
+- [SDESK-6002] fix: Slow responses due to mocked notification_client (#38)
+
 0.2.3 - 2021-05-06
 ==================
 

docs/client/python/client/images.rst

@@ -0,0 +1,6 @@
+:mod:`sams_client.endpoints.images` -- Images Endpoint
+======================================================
+
+.. automodule:: sams_client.endpoints.images
+    :members:
+    :member-order: bysource

docs/client/python/client/index.rst

@@ -9,3 +9,4 @@
     endpoint
     storage_destinations
     sets
+    images

docs/client/python/schemas/assets.rst

@@ -1,5 +1,23 @@
 :mod:`sams_client.schemas.assets` -- Assets
 ===========================================
 
+.. autoclass:: sams_client.schemas.assets.AssetStates
+    :members:
+
 .. automodule:: sams_client.schemas.assets
-    :members: ASSET_SCHEMA,ASSET_STATES
+    :members: ASSET_STATES
+
+.. autoclass:: sams_client.schemas.assets.IAssetTag
+    :members:
+
+.. autoclass:: sams_client.schemas.assets.IAssetRenditionArgs
+    :members:
+
+.. autoclass:: sams_client.schemas.assets.IAssetRendition
+    :members:
+
+.. autoclass:: sams_client.schemas.assets.IAsset
+    :members:
+    :member-order: bysource
+    :private-members:
+

docs/conf.py

@@ -65,9 +65,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.2.4'
+version = '0.3.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.2.4'
+release = '0.3.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -134,7 +134,7 @@
 # documentation.
 #
 html_theme_options = {
-    'description': 'SAMS server & client reference v0.2.4',
+    'description': 'SAMS server & client reference v0.3.0',
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -143,7 +143,7 @@
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
 #
-# html_title = 'SAMS v0.2.4'
+# html_title = 'SAMS v0.3.0'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #

docs/errors.rst

@@ -17,3 +17,4 @@ The following is a list of all the known errors that can occur.
    errors/sets
    errors/assets
    errors/amazon_s3
+   errors/asset_image

docs/errors/asset_image.rst

@@ -0,0 +1,7 @@
+:mod:`SamsAssetImageErrors` -- Asset Image Errors
+=================================================
+
+.. autoclass:: sams_client.errors.SamsAssetImageErrors.RenditionDimensionsNotProvided
+    :members:
+    :member-order: bysource
+    :undoc-members:

docs/index.rst

@@ -12,9 +12,41 @@ Welcome to SAMS documentation!
    :alt: Superdesk
    :class: floatinglogo
 
-Welcome. This is the home of SAMS technical documentation. You will learn
+Welcome. This is the home of the SAMS technical documentation. You will learn
 here mainly about the SAMS server application and client library.
 
+What is SAMS
+------------
+
+Super Asset Management Service (a.k.a. SAMS) is an API that provides the
+administration, production and consumption of Assets. In SAMS, an Asset is a
+file and it's associated metadata.
+
+Assets are stored in a Set, which can be thought of like a storage drive.
+Each Set has a dedicated Storage Destination, which can be one of the following:
+
+* Amazon Simple Storage Service (S3)
+* MongoDB GridFS
+
+The Asset's binary will be stored using the Set's configured Storage Destination,
+while the metadata will be stored in MongoDB and Elasticsearch.
+
+Managing Assets
+---------------
+
+All Assets must be managed (created, updated and deleted) through SAMS,
+as SAMS contains metadata and actions that are not available across all
+storage destination types.
+
+There are two ways to manage these Assets:
+
+* Using the :class:`~sams_client.client.SamsClient` Python client library
+* Using the Superdesk SAMS Workspace - a UI to manage Assets in SAMS
+
+We currently do not have a mechanism to import, or synchronise,
+existing Assets from S3 or GridFS into SAMS.
+
+
 Contents
 --------
 
@@ -26,6 +58,8 @@ Contents
     config
     cli
     technical_reference
+    api_reference
+    client_reference
     errors
     changelog
 

docs/technical_reference.rst

@@ -7,5 +7,3 @@ Technical Reference
 
     apps_reference
     server_reference
-    api_reference
-    client_reference

src/clients/python/sams_client/__init__.py

@@ -10,6 +10,7 @@
 # at https://www.sourcefabric.org/superdesk/license
 
 from .client import SamsClient # noqa
+from .schemas.assets import IAsset, IAssetTag, IAssetRendition, IAssetRenditionArgs # noqa
 
-__version__ = '0.2.4'
-__all__ = 'SamsClient'
+__version__ = '0.3.0'
+__all__ = ('SamsClient', 'IAsset', 'IAssetTag', 'IAssetRendition', 'IAssetRenditionArgs')

src/clients/python/sams_client/endpoints/images.py

@@ -9,6 +9,65 @@
 # AUTHORS and LICENSE files distributed with this source code, or
 # at https://www.sourcefabric.org/superdesk/license
 
+"""
+
+A set a collection of *Assets*. It is used as a way to organise and restrict access to
+the *Assets* it holds.
+
+All access to the binary or metadata of assets will go through this service. There must
+be at least one Set configured in the system.
+
+A single Set can be designated as the default Set. When access is requested to an asset
+without a set being provided, the default set will be used.
+
+Usage
+-----
+The Set service instance can be found under :data:`sams.sets.service` and used all::
+
+    from sams_client import SamsClient, IAsset, IAssetTag
+
+    client = SamsClient()
+
+    # Load the image file
+    with open("example_image.png", "rb") as image_file:
+        asset_binary = image_file.read()
+
+    set_id = client.sets.search().json()["_items"][0]["_id"]
+
+    # Upload a new Image Asset
+    response = client.assets.create(
+        docs=IAsset(
+            set_id=set_id,
+            filename="example_image.png",
+            name="test image renditions",
+            description="example image to test renditions",
+            tags=[
+                IAssetTag(code="test", name="test"),
+                IAssetTag(code="rendition", name="rendition")
+            ]
+        ),
+        files={"binary": asset_binary},
+        external_user_id="test_user_id"
+    )
+    new_asset = response.json()
+
+    # Generate a rendition
+    client.images.generate_rendition(
+        new_asset["_id"],
+        width=640,
+        height=640,
+        keep_proportions=True
+    )
+
+    # Download the newly created rendition
+    image_rendition = client.images.download(
+        new_asset["_id"],
+        width=640,
+        height=640,
+        keep_proportions=True
+    )
+"""
+
 from typing import Dict, Any, Callable, Union, Optional
 
 from bson import ObjectId
@@ -36,7 +95,19 @@ def download(
         keep_proportions: Optional[bool] = True,
         headers: Dict[str, Any] = None,
         callback: Callable[[requests.Response], requests.Response] = None
-    ):
+    ) -> requests.Response:
+        r"""Download an Image, optionally providing image dimensions
+
+        :param str item_id: The Asset ID
+        :param int width: Desired image width (optional)
+        :param int height: Desired image height (optional)
+        :param bool keep_proportions: If `true`, keeps image width/height ratio
+        :param dict headers: Dictionary of headers to apply
+        :param callback: A callback function to manipulate the response
+        :rtype: requests.Response
+        :return: The Asset binary, optionally resized
+        """
+
         params = {}
 
         if width:
@@ -56,14 +127,26 @@ def download(
         )
 
     def generate_rendition(
-            self,
-            item_id: Union[ObjectId, str],
-            width: Optional[int] = None,
-            height: Optional[int] = None,
-            keep_proportions: Optional[bool] = True,
-            headers: Dict[str, Any] = None,
-            callback: Callable[[requests.Response], requests.Response] = None
-    ):
+        self,
+        item_id: Union[ObjectId, str],
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        keep_proportions: Optional[bool] = True,
+        headers: Dict[str, Any] = None,
+        callback: Callable[[requests.Response], requests.Response] = None
+    ) -> requests.Response:
+        r"""Generates an Image rendition
+
+        :param str item_id: The Asset ID
+        :param int width: Desired image width (optional)
+        :param int height: Desired image height (optional)
+        :param bool keep_proportions: If `true`, keeps image width/height ratio
+        :param dict headers: Dictionary of headers to apply
+        :param callback: A callback function to manipulate the response
+        :rtype: requests.Response
+        :return: 200 status code if rendition generated successfully
+        """
+
         params = {}
 
         if width: