Skip to content

Commit 6dedb9f

Browse files
committed
fixed python sdk docs
1 parent ea7a0a7 commit 6dedb9f

6 files changed

Lines changed: 30 additions & 22 deletions

File tree

docs/python-sdk/api-reference/overview.mdx

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ client = ElementaryCloudClient(project_id, api_key, url)
3939
Where:
4040
- `project_id` is your Python project identifier (chosen by you, used to deduplicate and identify reported assets)
4141
- `api_key` is your API token (generated from the steps above)
42-
- `url` is the full SDK ingest endpoint URL: `{base_url}/sdk-ingest/{env_id}/batch`
42+
- `url` is the full SDK ingest endpoint URL (the Elementary team will provide you with this URL): `{base_url}/sdk-ingest/{env_id}/batch`
4343
- Example: `https://app.elementary-data.com/sdk-ingest/a6b2425d-36e2-4e13-8458-9825688ca1f2/batch`
4444

4545
## Test Context
@@ -75,15 +75,17 @@ You can also use context managers for inline tests:
7575
with elementary_test_context(asset=asset) as ctx:
7676
# Using context managers
7777
with ctx.boolean_test(name="my_test", description="Inline test") as my_bool_test:
78-
my_bool_test.assert_value(False)
78+
my_bool_test.assert_value(my_test_function())
7979

8080
with ctx.expected_values_test(
8181
name="country_count",
8282
expected=[2, 3],
8383
allow_none=True,
8484
metadata={"my_metadata_field": "my_metadata_value"},
8585
) as my_expected_values_test:
86+
# This will fail
8687
my_expected_values_test.assert_value(5)
88+
# This will pass
8789
my_expected_values_test.assert_value(3)
8890

8991
with ctx.expected_range_test(
@@ -143,7 +145,6 @@ except Exception as e:
143145
- **Run multiple tests in one context** - All tests in a single `elementary_test_context` are automatically batched
144146
- **Use descriptive test names** - Clear names help identify tests in the Elementary UI
145147
- **Include asset metadata** - Add descriptions, owners, tags, and dependencies to assets
146-
- **Handle errors gracefully** - Wrap `send_to_cloud` calls in try-except blocks
147148

148149
<Tip>
149150
All tests run within a single `elementary_test_context` are automatically batched and sent together.

docs/python-sdk/api-reference/table-assets.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ asset = TableAsset(
1717
description="string", # Optional: Table description
1818
owners=["string"], # Optional: List of owners (emails or usernames)
1919
tags=["string"], # Optional: List of tags
20-
depends_on=["string"] # Optional: List of upstream asset IDs
20+
depends_on=["string"] # Optional: List of upstream fully qualified table names
2121
)
2222
```
2323

@@ -37,7 +37,7 @@ asset = TableAsset(
3737
| `description` | string | Human-readable description of the table |
3838
| `owners` | list[string] | List of owners (email addresses or usernames) |
3939
| `tags` | list[string] | List of tags for categorization |
40-
| `depends_on` | list[string] | List of upstream asset IDs (e.g., `["prod.public.customers", "prod.public.orders"]`) for lineage tracking |
40+
| `depends_on` | list[string] | List of upstream fully qualified table names (e.g., `["prod.public.customers", "prod.public.orders"]`) for lineage tracking |
4141

4242
## Example
4343

docs/python-sdk/api-reference/test-decorators.mdx

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,8 @@ def test_function(df: pd.DataFrame) -> bool:
4949
| `tags` | list[str] | No | `None` | List of tags |
5050
| `owners` | list[str] | No | `None` | List of owners |
5151
| `metadata` | dict | No | `None` | Additional metadata |
52-
| `quality_dimension` | QualityDimension | No | `None` | Quality dimension (defaults to VALIDITY if column_name is set) |
53-
| `skip` | bool | No | `False` | Whether to skip this test |
52+
| `quality_dimension` | QualityDimension | No | `None` | Quality dimension (defaults to VALIDITY) |
53+
| `skip` | bool | No | `False` | Whether to skip this test. Useful if you want the test to appear in Elementary Cloud, but you don't want to execute it in this run. |
5454

5555
### Example
5656

@@ -68,7 +68,7 @@ def test_unique_ids(df: pd.DataFrame) -> bool:
6868

6969
## @expected_range
7070

71-
Tests that return a numeric value that should fall within a range.
71+
Tests that return a numeric value that should fall within a range. They can also return a list of numeric values or a pandas Series.
7272

7373
### Signature
7474

@@ -86,9 +86,11 @@ Tests that return a numeric value that should fall within a range.
8686
quality_dimension: QualityDimension | None = None,
8787
skip: bool = False,
8888
)
89-
def test_function(df: pd.DataFrame) -> float:
89+
def test_function(df: pd.DataFrame) -> float | list[float] | pd.Series:
9090
# Your test logic
91-
return 25.5 # Numeric value
91+
return df["age"].mean() # Numeric value
92+
# return [1, 2, 3] # Numeric values
93+
# return df["age"] # pandas Series
9294
```
9395

9496
### Parameters
@@ -120,7 +122,7 @@ def test_average_age(df: pd.DataFrame) -> float:
120122

121123
## @expected_values
122124

123-
Tests that return a value that should match one of a list of expected values.
125+
Tests that return a value (or values) that should match one of a list of expected values.
124126

125127
### Signature
126128

docs/python-sdk/guides/authentication.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,7 @@ If you receive a 404 error:
116116
- Verify your URL is correct and includes the correct environment ID
117117
- Check that the environment exists in your Elementary Cloud account
118118
- Ensure you have access to the environment
119+
- Contact the Elementary team for help
119120

120121
## Related Documentation
121122

docs/python-sdk/introduction.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ The SDK allows you to:
3232
- **Framework-agnostic** - Works with any Python testing framework (Great Expectations, DQX, custom code)
3333
- **Decorator-based API** - Simple decorators to define tests (`@boolean_test`, `@expected_range`, etc.)
3434
- **Context management** - Use `elementary_test_context` to automatically capture test results
35-
- **Unified observability** - Python tests appear alongside dbt tests and cloud tests in Elementary
35+
- **Unified observability** - Python tests appear alongside dbt tests and cloud tests in Elementary Cloud
3636
- **Full lineage** - Connect Python assets to dbt models, warehouse tables, and ML outputs
3737

3838
## Use Cases

docs/python-sdk/quickstart.mdx

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,8 @@ from elementary_python_sdk.core.tests import (
1919
boolean_test,
2020
elementary_test_context,
2121
expected_range,
22+
expected_values,
23+
row_count,
2224
)
2325
from elementary_python_sdk.core.types.asset import TableAsset
2426
```
@@ -59,20 +61,20 @@ def test_average_age(df: pd.DataFrame) -> float:
5961
severity="WARNING",
6062
description="Validate user count is within expected range",
6163
)
62-
def get_users_df(df: pd.DataFrame) -> pd.DataFrame:
63-
"""Return the dataframe - decorator calls len() on it."""
64+
def test_users_row_count(df: pd.DataFrame) -> pd.DataFrame:
65+
"""Return the DataFrame; the decorator calls len() on it."""
6466
return df
6567

6668
# Define an expected values test
6769
@expected_values(
68-
name="country_count",
69-
expected=2,
70+
name="only_valid_countries",
71+
expected=["Germany", "France", "Italy"],
7072
severity="ERROR",
71-
description="Should have exactly 2 countries",
73+
description="Should contain only valid countries",
7274
column_name="country",
7375
)
74-
def count_unique_countries(df: pd.DataFrame) -> int:
75-
return df["country"].nunique()
76+
def test_only_valid_countries(df: pd.DataFrame) -> pd.Series:
77+
return df["country"]
7678
```
7779

7880
## Step 4: Create Your Data Asset
@@ -109,6 +111,8 @@ def main():
109111
# Run tests - results are automatically captured
110112
test_average_age(users_df)
111113
test_unique_ids(users_df)
114+
test_users_row_count(users_df)
115+
test_only_valid_countries(users_df)
112116

113117
# Send results to Elementary Cloud
114118
PROJECT_ID = "my-python-project" # Your Python project identifier (used to deduplicate and identify assets)
@@ -191,15 +195,15 @@ def main():
191195

192196
client = ElementaryCloudClient(PROJECT_ID, API_KEY, URL)
193197
client.send_to_cloud(ctx)
198+
199+
if __name__ == "__main__":
200+
main()
194201
```
195202

196203
**Note:**
197204
- Replace `API_KEY` and `URL` with your actual credentials. The `URL` should be the full SDK ingest endpoint including your environment ID.
198205
- `PROJECT_ID` is your Python project identifier - choose any string to identify your code project. This will appear in the metadata of assets you report and is used for deduplication.
199206

200-
if __name__ == "__main__":
201-
main()
202-
```
203207

204208
## What Happens Next?
205209

0 commit comments

Comments
 (0)