Implements records result iterator

Author: 1pxone

README.md

@@ -40,14 +40,28 @@ user = db.records.create(
 )
 
 # Find records
-results = db.records.find({
+result = db.records.find({
     "where": {
         "age": {"$gte": 18},
         "name": {"$startsWith": "J"}
     },
     "limit": 10
 })
 
+# Work with SearchResult
+print(f"Found {len(result)} records out of {result.total} total")
+
+# Iterate over results
+for record in result:
+    print(f"User: {record.get('name')} (Age: {record.get('age')})")
+
+# Check if there are more results
+if result.has_more:
+    print("There are more records available")
+
+# Access specific records
+first_user = result[0] if result else None
+
 # Create relationships
 company = db.records.create(
     label="COMPANY",
@@ -83,6 +97,166 @@ db.records.create_many("COMPANY", {
 })
 ```
 
+## SearchResult API
+
+RushDB Python SDK uses a modern `SearchResult` container that follows Python SDK best practices similar to boto3, google-cloud libraries, and other popular SDKs.
+
+### SearchResult Features
+
+- **List-like access**: Index, slice, and iterate like a regular list
+- **Search context**: Access total count, pagination info, and the original search query
+- **Boolean conversion**: Use in if statements naturally
+- **Pagination support**: Built-in pagination information and `has_more` property
+
+### Basic Usage
+
+```python
+# Perform a search
+result = db.records.find({
+    "where": {"status": "active"},
+    "limit": 10,
+    "skip": 20
+})
+
+# Check if we have results
+if result:
+    print(f"Found {len(result)} records")
+
+# Access search result information
+print(f"Total matching records: {result.total}")
+print(f"Current page size: {result.count}")
+print(f"Records skipped: {result.skip}")
+print(f"Has more results: {result.has_more}")
+print(f"Search query: {result.search_query}")
+
+# Iterate over results
+for record in result:
+    print(f"Record: {record.get('name')}")
+
+# List comprehensions work
+names = [r.get('name') for r in result]
+
+# Indexing and slicing
+first_record = result[0] if result else None
+first_five = result[:5]
+```
+
+### SearchResult Properties
+
+| Property       | Type            | Description                              |
+| -------------- | --------------- | ---------------------------------------- |
+| `data`         | `List[Record]`  | The list of record results               |
+| `total`        | `int`           | Total number of matching records         |
+| `count`        | `int`           | Number of records in current result set  |
+| `limit`        | `Optional[int]` | Limit that was applied to the search     |
+| `skip`         | `int`           | Number of records that were skipped      |
+| `has_more`     | `bool`          | Whether there are more records available |
+| `search_query` | `SearchQuery`   | The search query used to generate result |
+
+### Pagination Example
+
+```python
+# Paginated search
+page_size = 10
+current_page = 0
+
+while True:
+    result = db.records.find({
+        "where": {"category": "electronics"},
+        "limit": page_size,
+        "skip": current_page * page_size,
+        "orderBy": {"created_at": "desc"}
+    })
+
+    if not result:
+        break
+
+    print(f"Page {current_page + 1}: {len(result)} records")
+
+    for record in result:
+        process_record(record)
+
+    if not result.has_more:
+        break
+
+    current_page += 1
+```
+
+## Improved Record API
+
+The Record class has been enhanced with better data access patterns and utility methods.
+
+### Enhanced Data Access
+
+```python
+# Create a record
+user = db.records.create("User", {
+    "name": "John Doe",
+    "email": "john@example.com",
+    "age": 30,
+    "department": "Engineering"
+})
+
+# Safe field access with defaults
+name = user.get("name")                    # "John Doe"
+phone = user.get("phone", "Not provided") # "Not provided"
+
+# Get clean user data (excludes internal fields like __id, __label)
+user_data = user.get_data()
+# Returns: {"name": "John Doe", "email": "john@example.com", "age": 30, "department": "Engineering"}
+
+# Get all data including internal fields
+full_data = user.get_data(exclude_internal=False)
+# Includes: __id, __label, __proptypes, etc.
+
+# Convenient fields property
+fields = user.fields  # Same as user.get_data()
+
+# Dictionary conversion
+user_dict = user.to_dict()  # Clean user data
+full_dict = user.to_dict(exclude_internal=False)  # All data
+
+# Direct field access
+user_name = user["name"]        # Direct access
+user_id = user["__id"]          # Internal field access
+```
+
+### Record Existence Checking
+
+```python
+# Safe existence checking (no exceptions)
+if user.exists():
+    print("Record is valid and accessible")
+    user.update({"status": "active"})
+else:
+    print("Record doesn't exist or is not accessible")
+
+# Perfect for validation workflows
+def process_record_safely(record):
+    if not record.exists():
+        return None
+    return record.get_data()
+
+# Conditional operations
+records = db.records.find({"where": {"status": "pending"}})
+for record in records:
+    if record.exists():
+        record.update({"processed_at": datetime.now()})
+```
+
+### String Representations
+
+```python
+user = db.records.create("User", {"name": "Alice Johnson"})
+
+print(repr(user))  # Record(id='abc-123', label='User')
+print(str(user))   # User: Alice Johnson
+
+# For records without names
+product = db.records.create("Product", {"sku": "ABC123"})
+print(str(product))  # Product (product-id-here)
+```
+
 ## Complete Documentation
 
 For comprehensive documentation, tutorials, and examples, please visit:
@@ -206,18 +380,18 @@ def find(
     search_query: Optional[SearchQuery] = None,
     record_id: Optional[str] = None,
     transaction: Optional[Transaction] = None
-) -> List[Record]
+) -> RecordSearchResult
 ```
 
 **Arguments:**
 
-- `query` (Optional[SearchQuery]): Search query parameters
+- `search_query` (Optional[SearchQuery]): Search query parameters
 - `record_id` (Optional[str]): Optional record ID to search from
 - `transaction` (Optional[Transaction]): Optional transaction object
 
 **Returns:**
 
-- `List[Record]`: List of matching records
+- `RecordSearchResult`: SearchResult container with matching records and metadata
 
 **Example:**
 
@@ -235,7 +409,24 @@ query = {
     "limit": 10
 }
 
-records = db.records.find(query=query)
+result = db.records.find(query=query)
+
+# Work with SearchResult
+print(f"Found {len(result)} out of {result.total} total records")
+
+# Iterate over results
+for record in result:
+    print(f"Employee: {record.get('name')} - {record.get('department')}")
+
+# Check pagination
+if result.has_more:
+    print("More results available")
+
+# Access specific records
+first_employee = result[0] if result else None
+
+# List operations
+senior_employees = [r for r in result if r.get('age', 0) > 30]
 ```
 
 ### delete()

pyproject.toml

@@ -1,12 +1,12 @@
 [tool.poetry]
 name = "rushdb"
-version = "1.4.0"
+version = "1.5.0"
 description = "RushDB Python SDK"
 authors = ["RushDB Team <hi@rushdb.com>"]
 license = "Apache-2.0"
 readme = "README.md"
-homepage = "https://github.com/rushdb/rushdb-python"
-repository = "https://github.com/rushdb/rushdb-python"
+homepage = "https://github.com/rush-db/rushdb-python"
+repository = "https://github.com/rush-db/rushdb-python"
 documentation = "https://docs.rushdb.com"
 packages = [{ include = "rushdb", from = "src" }]
 keywords = [

src/rushdb/__init__.py

@@ -8,12 +8,15 @@
 from .models.property import Property
 from .models.record import Record
 from .models.relationship import RelationshipDetachOptions, RelationshipOptions
+from .models.result import RecordSearchResult, SearchResult
 from .models.transaction import Transaction
 
 __all__ = [
     "RushDB",
     "RushDBError",
     "Record",
+    "RecordSearchResult",
+    "SearchResult",
     "Transaction",
     "Property",
     "RelationshipOptions",

src/rushdb/api/records.py

@@ -1,8 +1,9 @@
 import typing
-from typing import Any, Dict, List, Optional, Tuple, Union
+from typing import Any, Dict, List, Optional, Union
 
 from ..models.record import Record
 from ..models.relationship import RelationshipDetachOptions, RelationshipOptions
+from ..models.result import RecordSearchResult
 from ..models.search_query import SearchQuery
 from ..models.transaction import Transaction
 from .base import BaseAPI
@@ -427,7 +428,7 @@ def find(
         search_query: Optional[SearchQuery] = None,
         record_id: Optional[str] = None,
         transaction: Optional[Transaction] = None,
-    ) -> Tuple[List[Record], int]:
+    ) -> RecordSearchResult:
         """Search for and retrieve records matching the specified criteria.
 
         Searches the database for records that match the provided search query.
@@ -443,25 +444,34 @@ def find(
                 If provided, the operation will be part of the transaction. Defaults to None.
 
         Returns:
-            Tuple[List[Record], int]: A tuple containing:
-                - List[Record]: List of Record objects matching the search criteria
-                - int: Total count of matching records (may be larger than returned list if pagination applies)
-
-        Note:
-            The method includes exception handling that returns an empty list if an error occurs.
-            In production code, you may want to handle specific exceptions differently.
+            RecordSearchResult: A result object containing:
+                - Iterable list of Record objects matching the search criteria
+                - Total count of matching records (may be larger than returned list if pagination applies)
+                - Additional metadata about the search operation
+                - Convenient properties like .has_more, .count, etc.
 
         Example:
             >>> from rushdb.models.search_query import SearchQuery
             >>> records_api = RecordsAPI(client)
             >>>
             >>> # Find all records with a specific label
             >>> query = SearchQuery(labels=["User"])
-            >>> records, total = records_api.find(query)
-            >>> print(f"Found {len(records)} records out of {total} total")
+            >>> result = records_api.find(query)
+            >>> print(f"Found {result.count} records out of {result.total} total")
+            >>>
+            >>> # Iterate over results
+            >>> for record in result:
+            ...     print(f"User: {record.get('name', 'Unknown')}")
+            >>>
+            >>> # Access specific records
+            >>> first_user = result[0] if result else None
+            >>>
+            >>> # Check if there are more results
+            >>> if result.has_more:
+            ...     print("There are more records available")
             >>>
             >>> # Find records related to a specific record
-            >>> related_records, total = records_api.find(query, record_id="parent_123")
+            >>> related_result = records_api.find(query, record_id="parent_123")
         """
 
         try:
@@ -474,11 +484,17 @@ def find(
                 data=typing.cast(typing.Dict[str, typing.Any], search_query or {}),
                 headers=headers,
             )
-            return [
-                Record(self.client, record) for record in response.get("data")
-            ], response.get("total") or 0
+
+            records = [
+                Record(self.client, record) for record in response.get("data", [])
+            ]
+            total = response.get("total", 0)
+
+            return RecordSearchResult(
+                data=records, total=total, search_query=search_query
+            )
         except Exception:
-            return [], 0
+            return RecordSearchResult(data=[], total=0)
 
     def import_csv(
         self,

src/rushdb/client.py

@@ -240,7 +240,7 @@ def ping(self) -> bool:
             ...     return client
         """
         try:
-            self._make_request("GET", "/")
+            self._make_request("GET", "/settings")
             return True
         except RushDBError:
             return False

src/rushdb/models/__init__.py

@@ -0,0 +1,17 @@
+from .property import Property
+from .record import Record
+from .relationship import RelationshipDetachOptions, RelationshipOptions
+from .result import RecordSearchResult, SearchResult
+from .search_query import SearchQuery
+from .transaction import Transaction
+
+__all__ = [
+    "Property",
+    "Record",
+    "RelationshipDetachOptions",
+    "RelationshipOptions",
+    "RecordSearchResult",
+    "SearchResult",
+    "SearchQuery",
+    "Transaction",
+]