Skip to content

Commit 53b5b52

Browse files
1pxone1pxone
committed
Update docs and labels api
1 parent 84f0276 commit 53b5b52

File tree

7 files changed

+943
-63
lines changed

7 files changed

+943
-63
lines changed

‎pyproject.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[tool.poetry]
22
name = "rushdb"
3-
version = "1.2.0"
3+
version = "1.4.0"
44
description = "RushDB Python SDK"
55
authors = ["RushDB Team <hi@rushdb.com>"]
66
license = "Apache-2.0"

‎src/rushdb/api/labels.py

Lines changed: 65 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,76 @@
77

88

99
class LabelsAPI(BaseAPI):
10-
"""API for managing labels in RushDB."""
10+
"""API client for managing labels in RushDB.
1111
12-
def list(
12+
The LabelsAPI provides functionality for discovering and working with record labels
13+
in the database. Labels are used to categorize and type records, similar to table
14+
names in relational databases or document types in NoSQL databases.
15+
16+
This class handles:
17+
- Label discovery and listing
18+
- Label searching and filtering
19+
- Transaction support for operations
20+
21+
Labels help organize and categorize records, making it easier to query and
22+
understand the structure of data within the database.
23+
24+
Attributes:
25+
client: The underlying RushDB client instance for making HTTP requests.
26+
27+
Example:
28+
>>> from rushdb import RushDB
29+
>>> client = RushDB(api_key="your_api_key")
30+
>>> labels_api = client.labels
31+
>>>
32+
>>> # Get all labels in the database
33+
>>> all_labels = labels_api.find()
34+
>>> print("Available labels:", all_labels)
35+
>>>
36+
>>> # Search for specific labels
37+
>>> from rushdb.models.search_query import SearchQuery
38+
>>> query = SearchQuery(where={"name":{"$contains": "alice"}})
39+
>>> user_labels = labels_api.find(query)
40+
"""
41+
42+
def find(
1343
self,
1444
search_query: Optional[SearchQuery] = None,
1545
transaction: Optional[Transaction] = None,
1646
) -> List[str]:
17-
"""List all labels."""
47+
"""Search for and retrieve labels matching the specified criteria.
48+
49+
Discovers labels (record types) that exist in the database and can optionally
50+
filter them based on search criteria. Labels represent the different types
51+
or categories of records stored in the database.
52+
53+
Args:
54+
search_query (Optional[SearchQuery], optional): The search criteria to filter labels.
55+
If None, returns all labels in the database. Can include filters for
56+
label names, patterns, or other metadata. Defaults to None.
57+
transaction (Optional[Transaction], optional): Transaction context for the operation.
58+
If provided, the operation will be part of the transaction. Defaults to None.
59+
60+
Returns:
61+
List[str]: List of label names (strings) matching the search criteria.
62+
Each string represents a unique label/type used in the database.
63+
64+
Raises:
65+
RequestError: If the server request fails.
66+
67+
Example:
68+
>>> from rushdb.models.search_query import SearchQuery
69+
>>> labels_api = LabelsAPI(client)
70+
>>>
71+
>>> # Get all labels
72+
>>> all_labels = labels_api.find()
73+
>>> print("Database contains these record types:", all_labels)
74+
>>>
75+
>>> # Search for labels amongst records matching a pattern
76+
>>> query = SearchQuery(where={"name":{"$contains": "alice"}})
77+
>>> user_labels = labels_api.find(query)
78+
>>> print("User-related labels:", user_labels)
79+
"""
1880
headers = Transaction._build_transaction_header(transaction)
1981

2082
return self.client._make_request(

‎src/rushdb/api/properties.py

Lines changed: 153 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,20 +8,84 @@
88

99

1010
class PropertyValuesQuery(SearchQuery, total=False):
11-
"""Extended SearchQuery for property values endpoint with text search support."""
11+
"""Extended SearchQuery for property values endpoint with text search support.
12+
13+
This class extends the base SearchQuery to include additional search capabilities
14+
specifically for querying property values, including text-based search functionality.
15+
16+
Attributes:
17+
query (Optional[str]): Text search string to filter property values.
18+
When provided, performs a text-based search among the property values.
19+
"""
1220

1321
query: Optional[str] # For text search among values
1422

1523

1624
class PropertiesAPI(BaseAPI):
17-
"""API for managing properties in RushDB."""
25+
"""API client for managing properties in RushDB.
26+
27+
The PropertiesAPI provides functionality for working with database properties,
28+
including searching for properties, retrieving individual properties by ID,
29+
deleting properties, and querying property values. Properties represent
30+
metadata about the structure and characteristics of data in the database.
31+
32+
This class handles:
33+
- Property discovery and searching
34+
- Individual property retrieval
35+
- Property deletion
36+
- Property values querying with text search capabilities
37+
- Transaction support for all operations
38+
39+
Attributes:
40+
client: The underlying RushDB client instance for making HTTP requests.
41+
42+
Example:
43+
>>> from rushdb import RushDB
44+
>>> client = RushDB(api_key="your_api_key")
45+
>>> properties_api = client.properties
46+
>>>
47+
>>> # Find all properties
48+
>>> properties = properties_api.find()
49+
>>>
50+
>>> # Get a specific property
51+
>>> property_obj = properties_api.find_by_id("property_123")
52+
"""
1853

1954
def find(
2055
self,
2156
search_query: Optional[SearchQuery] = None,
2257
transaction: Optional[Transaction] = None,
2358
) -> List[Property]:
24-
"""List all properties."""
59+
"""Search for and retrieve properties matching the specified criteria.
60+
61+
Searches the database for properties that match the provided search query.
62+
Properties represent metadata about the database structure and can be
63+
filtered using various search criteria.
64+
65+
Args:
66+
search_query (Optional[SearchQuery], optional): The search criteria to filter properties.
67+
If None, returns all properties. Can include filters for property names,
68+
types, or other metadata. Defaults to None.
69+
transaction (Optional[Transaction], optional): Transaction context for the operation.
70+
If provided, the operation will be part of the transaction. Defaults to None.
71+
72+
Returns:
73+
List[Property]: List of Property objects matching the search criteria.
74+
75+
Raises:
76+
RequestError: If the server request fails.
77+
78+
Example:
79+
>>> from rushdb.models.search_query import SearchQuery
80+
>>> properties_api = PropertiesAPI(client)
81+
>>>
82+
>>> # Find all properties
83+
>>> all_properties = properties_api.find()
84+
>>>
85+
>>> # Find properties with specific criteria
86+
>>> query = SearchQuery(where={"age":{"$gte": 30}})
87+
>>> string_properties = properties_api.find(query)
88+
"""
2589
headers = Transaction._build_transaction_header(transaction)
2690

2791
return self.client._make_request(
@@ -34,7 +98,29 @@ def find(
3498
def find_by_id(
3599
self, property_id: str, transaction: Optional[Transaction] = None
36100
) -> Property:
37-
"""Get a property by ID."""
101+
"""Retrieve a specific property by its unique identifier.
102+
103+
Fetches a single property from the database using its unique ID.
104+
This method is useful when you know the exact property you want to retrieve.
105+
106+
Args:
107+
property_id (str): The unique identifier of the property to retrieve.
108+
transaction (Optional[Transaction], optional): Transaction context for the operation.
109+
If provided, the operation will be part of the transaction. Defaults to None.
110+
111+
Returns:
112+
Property: The Property object with the specified ID.
113+
114+
Raises:
115+
ValueError: If the property_id is invalid or empty.
116+
NotFoundError: If no property exists with the specified ID.
117+
RequestError: If the server request fails.
118+
119+
Example:
120+
>>> properties_api = PropertiesAPI(client)
121+
>>> property_obj = properties_api.find_by_id("prop_123")
122+
>>> print(property_obj.name)
123+
"""
38124
headers = Transaction._build_transaction_header(transaction)
39125

40126
return self.client._make_request(
@@ -44,7 +130,33 @@ def find_by_id(
44130
def delete(
45131
self, property_id: str, transaction: Optional[Transaction] = None
46132
) -> None:
47-
"""Delete a property."""
133+
"""Delete a property from the database.
134+
135+
Permanently removes a property and all its associated metadata from the database.
136+
This operation cannot be undone, so use with caution.
137+
138+
Args:
139+
property_id (str): The unique identifier of the property to delete.
140+
transaction (Optional[Transaction], optional): Transaction context for the operation.
141+
If provided, the operation will be part of the transaction. Defaults to None.
142+
143+
Returns:
144+
None: This method does not return a value.
145+
146+
Raises:
147+
ValueError: If the property_id is invalid or empty.
148+
NotFoundError: If no property exists with the specified ID.
149+
RequestError: If the server request fails.
150+
151+
Warning:
152+
This operation permanently deletes the property and cannot be undone.
153+
Ensure you have proper backups and confirmation before deleting properties.
154+
155+
Example:
156+
>>> properties_api = PropertiesAPI(client)
157+
>>> properties_api.delete("prop_123")
158+
>>> # Property is now permanently deleted
159+
"""
48160
headers = Transaction._build_transaction_header(transaction)
49161

50162
return self.client._make_request(
@@ -57,7 +169,42 @@ def values(
57169
search_query: Optional[PropertyValuesQuery] = None,
58170
transaction: Optional[Transaction] = None,
59171
) -> PropertyValuesData:
60-
"""Get values data for a property."""
172+
"""Retrieve and search values data for a specific property.
173+
174+
Gets statistical and analytical data about the values stored in a particular property,
175+
including value distributions, counts, and other metadata. Supports text-based
176+
searching within the property values.
177+
178+
Args:
179+
property_id (str): The unique identifier of the property to analyze.
180+
search_query (Optional[PropertyValuesQuery], optional): Extended search query
181+
that supports text search among property values. Can include:
182+
- Standard SearchQuery filters
183+
- query (str): Text search string to filter values
184+
Defaults to None.
185+
transaction (Optional[Transaction], optional): Transaction context for the operation.
186+
If provided, the operation will be part of the transaction. Defaults to None.
187+
188+
Returns:
189+
PropertyValuesData: Object containing statistical and analytical data about
190+
the property's values, including distributions, counts, and value samples.
191+
192+
Raises:
193+
ValueError: If the property_id is invalid or empty.
194+
NotFoundError: If no property exists with the specified ID.
195+
RequestError: If the server request fails.
196+
197+
Example:
198+
>>> properties_api = PropertiesAPI(client)
199+
>>>
200+
>>> # Get all values data for a property
201+
>>> values_data = properties_api.values("prop_123")
202+
>>> print(f"Total values: {values_data.total}")
203+
>>>
204+
>>> # Search for specific values
205+
>>> query = PropertyValuesQuery(query="search_text")
206+
>>> filtered_values = properties_api.values("prop_123", query)
207+
"""
61208
headers = Transaction._build_transaction_header(transaction)
62209

63210
return self.client._make_request(

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy