Merge pull request #50 from release-engineering/upd8docs

Update StArMap Documentations for APIv2

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

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")
 
 

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:

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__

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))