Docs: Add usage samples for each cache option (#112)

Author: aaronsteers

airbyte/caches/bigquery.py

@@ -1,5 +1,19 @@
 # Copyright (c) 2024 Airbyte, Inc., all rights reserved.
-"""A BigQuery implementation of the cache."""
+"""A BigQuery implementation of the cache.
+
+## Usage Example
+
+```python
+import airbyte as ab
+from airbyte.caches import BigQueryCache
+
+cache = BigQueryCache(
+    project_name="myproject",
+    dataset_name="mydataset",
+    credentials_path="path/to/credentials.json",
+)
+```
+"""
 
 from __future__ import annotations
 
@@ -17,8 +31,13 @@ class BigQueryCache(CacheBase):
     """The BigQuery cache implementation."""
 
     project_name: str
+    """The name of the project to use. In BigQuery, this is equivalent to the database name."""
+
     dataset_name: str = "airbyte_raw"
+    """The name of the dataset to use. In BigQuery, this is equivalent to the schema name."""
+
     credentials_path: str
+    """The path to the credentials file to use."""
 
     _sql_processor_class: type[BigQuerySqlProcessor] = BigQuerySqlProcessor
 

airbyte/caches/duckdb.py

@@ -1,5 +1,17 @@
 # Copyright (c) 2023 Airbyte, Inc., all rights reserved.
-"""A DuckDB implementation of the cache."""
+"""A DuckDB implementation of the PyAirbyte cache.
+
+## Usage Example
+
+```python
+from airbyte as ab
+from airbyte.caches import DuckDBCache
+
+cache = DuckDBCache(
+    db_path="/path/to/my/database.duckdb",
+    schema_name="myschema",
+)
+"""
 
 from __future__ import annotations
 
@@ -27,8 +39,8 @@ class DuckDBCache(CacheBase):
     db_path: Union[Path, str]
     """Normally db_path is a Path object.
 
-    There are some cases, such as when connecting to MotherDuck, where it could be a string that
-    is not also a path, such as "md:" to connect the user's default MotherDuck DB.
+    The database name will be inferred from the file name. For example, given a `db_path` of
+    `/path/to/my/my_db.duckdb`, the database name is `my_db`.
     """
 
     schema_name: str = "main"

airbyte/caches/motherduck.py

@@ -1,4 +1,18 @@
-"""A cache implementation for the MotherDuck service, built on DuckDB."""
+"""A MotherDuck implementation of the PyAirbyte cache, built on DuckDB.
+
+## Usage Example
+
+```python
+from airbyte as ab
+from airbyte.caches import MotherDuckCache
+
+cache = MotherDuckCache(
+    database="mydatabase",
+    schema_name="myschema",
+    api_key=ab.get_secret("MOTHERDUCK_API_KEY"),
+)
+"""
+
 from __future__ import annotations
 
 from overrides import overrides

airbyte/caches/postgres.py

@@ -1,5 +1,21 @@
 # Copyright (c) 2023 Airbyte, Inc., all rights reserved.
-"""A Postgres implementation of the cache."""
+"""A Postgres implementation of the PyAirbyte cache.
+
+## Usage Example
+
+```python
+from airbyte as ab
+from airbyte.caches import PostgresCache
+
+cache = PostgresCache(
+    host="myhost",
+    port=5432,
+    username="myusername",
+    password=ab.get_secret("POSTGRES_PASSWORD"),
+    database="mydatabase",
+)
+```
+"""
 
 from __future__ import annotations
 

airbyte/caches/snowflake.py

@@ -1,5 +1,23 @@
 # Copyright (c) 2023 Airbyte, Inc., all rights reserved.
-"""A Snowflake implementation of the cache."""
+"""A Snowflake implementation of the PyAirbyte cache.
+
+## Usage Example
+
+```python
+from airbyte as ab
+from airbyte.caches import SnowflakeCache
+
+cache = SnowflakeCache(
+    account="myaccount",
+    username="myusername",
+    password=ab.get_secret("SNOWFLAKE_PASSWORD"),
+    warehouse="mywarehouse",
+    database="mydatabase",
+    role="myrole",
+    schema_name="myschema",
+)
+```
+"""
 
 from __future__ import annotations