feat: add APIs for working with Stardog Cloud public API

docs/conf.py

@@ -40,13 +40,20 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinxcontrib.autodoc_pydantic",
     "sphinx_autodoc_typehints",
     "sphinx.ext.doctest",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "recommonmark",
 ]
 
+# https://autodoc-pydantic.readthedocs.io/en/stable/users/installation.html
+autodoc_pydantic_model_show_json = False
+autodoc_pydantic_settings_show_json = False
+autosummary_generate = True
+
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 

docs/index.rst

@@ -12,6 +12,8 @@ pystardog
 
    README.md
    source/stardog
+   source/stardog.cloud
+
 
 Indices and tables
 ==================

docs/requirements.txt

@@ -5,3 +5,4 @@ contextlib2==21.6.0
 requests-toolbelt==1.0.0
 recommonmark==0.5.0
 requests==2.31.0
+autodoc_pydantic==2.2.0

docs/source/stardog.cloud.rst

@@ -0,0 +1,105 @@
+Stardog Cloud
+###############
+
+The :obj:`stardog.cloud` subpackage provides clients for accessing Stardog Cloud services, such as `Stardog Voicebox <https://stardog.ai/>`_.
+
+.. list-table:: Clients
+    :widths: 50 50
+    :header-rows: 1
+
+    * - Class
+      - Description
+    * - :class:`stardog.cloud.client.Client`
+      - Ideal for simple blocking operations in traditional Python applications.
+    * - :class:`stardog.cloud.client.AsyncClient`
+      - Suitable for async programming models, such as ``asyncio``.
+
+Voicebox Integration
+************************
+
+Access Stardog's Voicebox capabilities through an instance of :class:`stardog.cloud.voicebox.VoiceboxApp` class.
+
+.. note::
+   The :class:`stardog.cloud.voicebox.VoiceboxApp` provides both synchronous and asynchronous methods, offering the same functionality. Asynchronous methods are prefixed with `async_` and return coroutines that can be awaited, while synchronous methods return objects directly. For example, :obj:`stardog.cloud.voicebox.VoiceboxApp.async_ask` returns a coroutine, while :obj:`stardog.cloud.voicebox.VoiceboxApp.ask` returns a :class:`stardog.cloud.voicebox.VoiceboxAnswer`.
+
+
+
+Synchronous usage
+========================
+
+.. code-block:: python
+
+    from stardog.cloud.client import Client
+
+    with Client() as client:
+        app = client.voicebox_app(app_api_token="your-token", client_id="your-client-id")
+        response = app.ask(question="Your question here")
+
+Asynchronous usage
+========================
+
+
+.. code-block:: python
+
+    from stardog.cloud.client import AsyncClient
+
+    async with AsyncClient() as client:
+        app = client.voicebox_app(app_api_token="your-token", client_id="your-client-id")
+        response = await app.async_ask(question="Your question here")
+
+
+Error Handling
+========================
+
+The package raises custom exceptions defined in the :obj:`stardog.cloud.exceptions` module. These exceptions can be caught when interacting with the Stardog Cloud clients.
+
+All clients raise exceptions if needed, with :class:`stardog.cloud.exceptions.StardogCloudException` serving as the base exception for any error raised.
+
+.. code-block:: python
+
+    from stardog.cloud.exceptions import (
+        StardogCloudException,
+        RateLimitExceededException
+    )
+
+    try:
+        with Client() as client:
+            app = client.voicebox_app(app_api_token="your-token", client_id="your-client-id")
+            response = app.ask(question="Your question")
+    except RateLimitExceededException as e:
+        print(f"Rate limit exceeded: {e}")
+    except StardogCloudException as e:
+        print(f"Error occurred: {e}")
+
+
+
+API Reference
+*********************
+
+stardog.cloud.client
+============================
+
+.. automodule:: stardog.cloud.client
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :special-members: __init__
+
+stardog.cloud.voicebox
+============================
+
+.. automodule:: stardog.cloud.voicebox
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :special-members: __init__
+
+stardog.cloud.exceptions
+============================
+
+.. automodule:: stardog.cloud.exceptions
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :special-members: __init__
+

docs/source/stardog.rst

@@ -1,8 +1,12 @@
-Modules
-=======
+Stardog
+#######
+
+
+API Reference
+*********************
 
 stardog.connection
-------------------
+==================
 
 .. automodule:: stardog.connection
     :members:
@@ -11,7 +15,7 @@ stardog.connection
     :special-members: __init__
 
 stardog.admin
--------------
+=============
 
 .. automodule:: stardog.admin
     :members:
@@ -20,7 +24,7 @@ stardog.admin
     :special-members: __init__
 
 stardog.content
----------------
+===============
 
 .. automodule:: stardog.content
     :members:
@@ -29,7 +33,7 @@ stardog.content
     :special-members: __init__
 
 stardog.results
----------------
+===============
 
 .. automodule:: stardog.results
     :members:
@@ -38,7 +42,7 @@ stardog.results
     :special-members: __init__
 
 stardog.exceptions
-------------------
+==================
 
 .. automodule:: stardog.exceptions
     :members:

requirements.txt

@@ -3,3 +3,5 @@ requests-toolbelt==1.0.0
 contextlib2==0.5.5
 recommonmark==0.5.0
 rdflib>=6.0.0
+httpx>=0.27.0
+pydantic>=2.7.0

stardog/cloud/__init__.py

@@ -0,0 +1,3 @@
+from .client import AsyncClient, Client
+
+__all__ = ["AsyncClient", "Client"]