From 60676d7feec1812608b8c1cd8bbf69ae2908547c Mon Sep 17 00:00:00 2001 From: Jonathan Gangi Date: Wed, 2 Oct 2024 16:40:49 -0300 Subject: [PATCH] Update StArMap Documentations for APIv2 Update the StArMap Clien's documentation to include the APIv2 entities and mark APIv1 as deprecated. Refers to SPSTRAT-384 --- docs/client/usage.rst | 28 ++++++++++++------------- docs/index.rst | 4 ++-- docs/model/models.rst | 42 +++++++++++++++++++++++++++++++++++++- docs/provider/provider.rst | 12 ++++++++++- starmap_client/models.py | 11 ++++++++-- 5 files changed, 76 insertions(+), 21 deletions(-) diff --git a/docs/client/usage.rst b/docs/client/usage.rst index 1580618..352358d 100644 --- a/docs/client/usage.rst +++ b/docs/client/usage.rst @@ -17,11 +17,11 @@ In this mode the :class:`~starmap_client.StarmapClient` will always request data from starmap_client import StarmapClient # Initialize the online client with the URL only - client = StarmapClient(url="https://starmap.example.com", api_version="v1") + client = StarmapClient(url="https://starmap.example.com", api_version="v2") # Alternatively you can create the session and inject it from starmap_client.session import StarmapSession - session = StarmapSession("https://starmap.example.com", api_version="v1", retries=5, backoff_factor=5.0) + session = StarmapSession("https://starmap.example.com", api_version="v2", retries=5, backoff_factor=5.0) client = StarmapClient(session=session) ... # Query @@ -41,18 +41,17 @@ In this mode the :class:`~starmap_client.StarmapClient` will always request data import json from starmap_client import StarmapClient from starmap_client.session import StarmapMockSession - from starmap_client.models import QueryResponse - from starmap_client.providers import InMemoryMapProvider + from starmap_client.models import QueryResponseContainer + from starmap_client.providers import InMemoryMapProviderV2 - # Load the QueryResponse models from somewhere + # Load the QueryResponseContainer models from somewhere with open("path_to_your_data.json", 'r') as f: qr_data = json.load(f) # Create the offline client - qr = QueryResponse.from_json(qr_data) - responses = [qr] # in this case it only contains 1 object, but it supports more - provider = InMemoryMapProvider(responses) - session = StarmapMockSession("fake.starmap.com", "v1") + container = QueryResponseContainer.from_json(qr_data) + provider = InMemoryMapProviderV2(container) + session = StarmapMockSession("fake.starmap.com", "v2") client = StarmapClient(session=session, provider=provider) # Query @@ -69,17 +68,16 @@ only proceed to query over network if the local provider doesn't have the reques import json from starmap_client import StarmapClient - from starmap_client.models import QueryResponse - from starmap_client.providers import InMemoryMapProvider + from starmap_client.models import QueryResponseContainer + from starmap_client.providers import InMemoryMapProviderV2 - # Load the QueryResponse models from somewhere + # Load the QueryResponseContainer models from somewhere with open("path_to_your_data.json", 'r') as f: qr_data = json.load(f) # Create the offline client - qr = QueryResponse.from_json(qr_data) - responses = [qr] # in this case it only contains 1 object, but it supports more - provider = InMemoryMapProvider(responses) + container = QueryResponseContainer.from_json(qr_data) + provider = InMemoryMapProviderV2(container) client = StarmapClient(url="https://starmap.example.com", provider=provider) # Query diff --git a/docs/index.rst b/docs/index.rst index e50cce4..cba9f48 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,8 +34,8 @@ use it to communicate with ``StArMap``: from starmap_client import StarmapClient import logging - # Alternatively you can pass the api_version as well. Defaults to "v1". - # client = StarmapClient(url="https://starmap.example.com", api_version="v1") + # Alternatively you can pass the api_version as well. Defaults to "v2". + # client = StarmapClient(url="https://starmap.example.com", api_version="v2") client = StarmapClient(url="https://starmap.example.com") diff --git a/docs/model/models.rst b/docs/model/models.rst index 04f5313..8b58fc2 100644 --- a/docs/model/models.rst +++ b/docs/model/models.rst @@ -4,6 +4,35 @@ Models The models returned by ``StarmapClient``. +APIv2 +----- + +.. autoclass:: starmap_client.models.QueryResponseContainer() + :members: + :show-inheritance: + +.. autoclass:: starmap_client.models.QueryResponseEntity() + :members: + :show-inheritance: + +.. autoclass:: starmap_client.models.MappingResponseObject() + :members: + :show-inheritance: + +.. autoclass:: starmap_client.models.BillingCodeRule() + :members: + :show-inheritance: + + +APIv1 (Deprecated) +------------------ + +.. autoclass:: starmap_client.models.QueryResponse() + :members: + +Common +------ + .. autoclass:: starmap_client.models.Policy() :members: @@ -15,6 +44,17 @@ The models returned by ``StarmapClient``. .. autoclass:: starmap_client.models.Destination() :members: +Utils +----- -.. autoclass:: starmap_client.models.QueryResponse() +.. autoclass:: starmap_client.models.Workflow() + :members: + +.. autoclass:: starmap_client.models.BillingImageType() + :members: + +.. autoclass:: starmap_client.models.StarmapJSONDecodeMixin() + :members: + +.. autoclass:: starmap_client.models.MetaMixin() :members: diff --git a/docs/provider/provider.rst b/docs/provider/provider.rst index 26d2cf8..fb17552 100644 --- a/docs/provider/provider.rst +++ b/docs/provider/provider.rst @@ -14,6 +14,16 @@ Implementations Memory Based ^^^^^^^^^^^^^^^^^^^^^^ -.. autoclass:: starmap_client.providers.InMemoryMapProvider + +APIv2 +~~~~~ +.. autoclass:: starmap_client.providers.InMemoryMapProviderV2 + :members: + :special-members: __init__ + +APIv1 (deprecated) +~~~~~~~~~~~~~~~~~~ + +.. autoclass:: starmap_client.providers.InMemoryMapProviderV1 :members: :special-members: __init__ diff --git a/starmap_client/models.py b/starmap_client/models.py index 2f5a02f..8007360 100644 --- a/starmap_client/models.py +++ b/starmap_client/models.py @@ -56,8 +56,10 @@ class Workflow(str, Enum): """Define the valid workflows for StArMap.""" community = "community" + """Workflow ``community``.""" stratosphere = "stratosphere" + """Workflow ``stratosphere`` for marketplaces.""" @frozen @@ -285,8 +287,13 @@ class BillingImageType(str, Enum): """Define the image type for :class:`~BillingCodeRule` for APIv2.""" access = "access" + """Billing type ``access``.""" + hourly = "hourly" + """Billing type ``hourly``.""" + marketplace = "marketplace" + """Billing type ``marketplace``.""" @frozen @@ -316,7 +323,7 @@ class BillingCodeRule(StarmapJSONDecodeMixin): @frozen -class MappingResponseObject(StarmapJSONDecodeMixin, MetaMixin): +class MappingResponseObject(MetaMixin, StarmapJSONDecodeMixin): """Represent a single mapping response from :class:`~QueryResponseObject` for APIv2.""" destinations: List[Destination] = field( @@ -361,7 +368,7 @@ def _preprocess_json(cls, json: Any) -> Dict[str, Any]: @frozen -class QueryResponseEntity(StarmapJSONDecodeMixin, MetaMixin): +class QueryResponseEntity(MetaMixin, StarmapJSONDecodeMixin): """Represent a single query response entity from StArMap APIv2.""" name: str = field(validator=instance_of(str))