# SiftDB Python Client
The official Python client library for SiftDB HTTP API.
## Installation
```bash
pip install siftdb
```
## Quick Start
### Basic Usage
```python
from siftdb import SiftDBClient
# Create client instance
client = SiftDBClient(
base_url="http://localhost:8080",
default_collection="/path/to/my/collection"
)
# Search for text
results = client.search(
query="function main",
path_filter="**/*.py",
limit=50
)
print(f"Found {results.total_matches} matches in {results.duration_ms}ms")
for hit in results.results:
print(f"{hit.file_path}:{hit.line_number}: {hit.line_content}")
```
### Context Manager Usage
```python
with SiftDBClient(base_url="http://localhost:8080") as client:
results = client.search("error handling")
print(f"Found {len(results.results)} results")
```
### Import Files
```python
# Import files into a collection
import_result = client.import_files(
source_path="/path/to/source",
include_patterns=["**/*.py", "**/*.md"],
exclude_patterns=["**/__pycache__/**", "**/.*"]
)
print(f"Imported {import_result.files_ingested} files")
print(f"Skipped {import_result.files_skipped} files")
if import_result.errors > 0:
print(f"Encountered {import_result.errors} errors")
```
### List Collections
```python
# List available collections
collections = client.list_collections()
for collection in collections.collections:
print(f"{collection.name}: {collection.total_files} files, {collection.total_size_bytes} bytes")
```
### Health Check
```python
# Check server health
health = client.health()
print(f"Server status: {health.status}")
print(f"Server version: {health.version}")
```
## API Reference
### Client Configuration
```python
SiftDBClient(
base_url="http://localhost:8080", # Server URL
timeout=30, # Request timeout in seconds
default_collection="/path/to/db" # Default collection path
)
```
### Search Parameters
```python
client.search(
query="search text", # Required: search query
collection="/path/to/db", # Optional: override default collection
path_filter="**/*.py", # Optional: glob pattern for file filtering
regex=False, # Optional: treat query as regex
limit=1000 # Optional: max results
)
```
### Import Parameters
```python
client.import_files(
source_path="/path/to/source", # Required: source directory
collection="/path/to/collection", # Optional: override default collection
include_patterns=["**/*.py"], # Optional: files to include
exclude_patterns=["**/build/**"] # Optional: files to exclude
)
```
## Error Handling
```python
from siftdb import SiftDBClient, SiftDBException
try:
client = SiftDBClient()
results = client.search("my query")
except SiftDBException as e:
print(f"SiftDB Error: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
```
## Data Models
### SearchResponse
```python
@dataclass
class SearchResponse:
query: str # Original search query
total_matches: int # Total number of matches
results: List[SearchResult] # Search results
duration_ms: float # Search duration
```
### SearchResult
```python
@dataclass
class SearchResult:
file_path: str # File path of the match
line_number: int # Line number where match occurred
line_content: str # Content of the matching line
```
### ImportResponse
```python
@dataclass
class ImportResponse:
message: str # Import completion message
files_ingested: int # Number of files imported
files_skipped: int # Number of files skipped
errors: int # Number of errors encountered
duration_ms: float # Import duration
```
## Requirements
- Python 3.8+
- requests >= 2.25.0
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/siftdb/siftdb",
"name": "siftdb",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "database search index full-text http api client",
"author": "SiftDB Team",
"author_email": "support@siftdb.dev",
"download_url": "https://files.pythonhosted.org/packages/2f/3c/f9dd55ee617c8a43022678e6cbb684fc67188cad97f39666c0c46d83a8b6/siftdb-0.2.2.tar.gz",
"platform": null,
"description": "# SiftDB Python Client\n\nThe official Python client library for SiftDB HTTP API.\n\n## Installation\n\n```bash\npip install siftdb\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom siftdb import SiftDBClient\n\n# Create client instance\nclient = SiftDBClient(\n base_url=\"http://localhost:8080\",\n default_collection=\"/path/to/my/collection\"\n)\n\n# Search for text\nresults = client.search(\n query=\"function main\",\n path_filter=\"**/*.py\",\n limit=50\n)\n\nprint(f\"Found {results.total_matches} matches in {results.duration_ms}ms\")\nfor hit in results.results:\n print(f\"{hit.file_path}:{hit.line_number}: {hit.line_content}\")\n```\n\n### Context Manager Usage\n\n```python\nwith SiftDBClient(base_url=\"http://localhost:8080\") as client:\n results = client.search(\"error handling\")\n print(f\"Found {len(results.results)} results\")\n```\n\n### Import Files\n\n```python\n# Import files into a collection\nimport_result = client.import_files(\n source_path=\"/path/to/source\",\n include_patterns=[\"**/*.py\", \"**/*.md\"],\n exclude_patterns=[\"**/__pycache__/**\", \"**/.*\"]\n)\n\nprint(f\"Imported {import_result.files_ingested} files\")\nprint(f\"Skipped {import_result.files_skipped} files\")\nif import_result.errors > 0:\n print(f\"Encountered {import_result.errors} errors\")\n```\n\n### List Collections\n\n```python\n# List available collections\ncollections = client.list_collections()\nfor collection in collections.collections:\n print(f\"{collection.name}: {collection.total_files} files, {collection.total_size_bytes} bytes\")\n```\n\n### Health Check\n\n```python\n# Check server health\nhealth = client.health()\nprint(f\"Server status: {health.status}\")\nprint(f\"Server version: {health.version}\")\n```\n\n## API Reference\n\n### Client Configuration\n\n```python\nSiftDBClient(\n base_url=\"http://localhost:8080\", # Server URL\n timeout=30, # Request timeout in seconds\n default_collection=\"/path/to/db\" # Default collection path\n)\n```\n\n### Search Parameters\n\n```python\nclient.search(\n query=\"search text\", # Required: search query\n collection=\"/path/to/db\", # Optional: override default collection\n path_filter=\"**/*.py\", # Optional: glob pattern for file filtering\n regex=False, # Optional: treat query as regex\n limit=1000 # Optional: max results\n)\n```\n\n### Import Parameters\n\n```python\nclient.import_files(\n source_path=\"/path/to/source\", # Required: source directory\n collection=\"/path/to/collection\", # Optional: override default collection\n include_patterns=[\"**/*.py\"], # Optional: files to include\n exclude_patterns=[\"**/build/**\"] # Optional: files to exclude\n)\n```\n\n## Error Handling\n\n```python\nfrom siftdb import SiftDBClient, SiftDBException\n\ntry:\n client = SiftDBClient()\n results = client.search(\"my query\")\nexcept SiftDBException as e:\n print(f\"SiftDB Error: {e}\")\nexcept Exception as e:\n print(f\"Unexpected error: {e}\")\n```\n\n## Data Models\n\n### SearchResponse\n\n```python\n@dataclass\nclass SearchResponse:\n query: str # Original search query\n total_matches: int # Total number of matches\n results: List[SearchResult] # Search results\n duration_ms: float # Search duration\n```\n\n### SearchResult\n\n```python\n@dataclass\nclass SearchResult:\n file_path: str # File path of the match\n line_number: int # Line number where match occurred\n line_content: str # Content of the matching line\n```\n\n### ImportResponse\n\n```python\n@dataclass\nclass ImportResponse:\n message: str # Import completion message\n files_ingested: int # Number of files imported\n files_skipped: int # Number of files skipped\n errors: int # Number of errors encountered\n duration_ms: float # Import duration\n```\n\n## Requirements\n\n- Python 3.8+\n- requests >= 2.25.0\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": null,
"summary": "Python client library for SiftDB HTTP API",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/siftdb/siftdb"
},
"split_keywords": [
"database",
"search",
"index",
"full-text",
"http",
"api",
"client"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "546014b6b68818bf774b9e9cd011573950d8a218f0d235dc3277d9f4c3361c8b",
"md5": "bcc8f5b9d9b1ac0449d25b299841e8b8",
"sha256": "054d4b71c51571dee4ab891fc310683b68f4d0ada623d45d478cd793f350c3f8"
},
"downloads": -1,
"filename": "siftdb-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bcc8f5b9d9b1ac0449d25b299841e8b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5867,
"upload_time": "2025-09-06T17:36:20",
"upload_time_iso_8601": "2025-09-06T17:36:20.261883Z",
"url": "https://files.pythonhosted.org/packages/54/60/14b6b68818bf774b9e9cd011573950d8a218f0d235dc3277d9f4c3361c8b/siftdb-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2f3cf9dd55ee617c8a43022678e6cbb684fc67188cad97f39666c0c46d83a8b6",
"md5": "993abf2433f6f3cae74b6e7f81a4d211",
"sha256": "a53945ab0dc9c05da93428a75f34c50ff0474ea6b59f14d347b9e09a00771468"
},
"downloads": -1,
"filename": "siftdb-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "993abf2433f6f3cae74b6e7f81a4d211",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5280,
"upload_time": "2025-09-06T17:36:21",
"upload_time_iso_8601": "2025-09-06T17:36:21.904001Z",
"url": "https://files.pythonhosted.org/packages/2f/3c/f9dd55ee617c8a43022678e6cbb684fc67188cad97f39666c0c46d83a8b6/siftdb-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-06 17:36:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "siftdb",
"github_project": "siftdb",
"github_not_found": true,
"lcname": "siftdb"
}
JSON
