quicksearch-python-sdk 1.0.4__tar.gz

quicksearch_python_sdk-1.0.4/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

quicksearch_python_sdk-1.0.4/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

quicksearch_python_sdk-1.0.4/.python-version

@@ -0,0 +1 @@
+3.11

quicksearch_python_sdk-1.0.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 QuickSearch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quicksearch_python_sdk-1.0.4/PKG-INFO

@@ -0,0 +1,386 @@
+Metadata-Version: 2.4
+Name: quicksearch-python-sdk
+Version: 1.0.4
+Summary: Python SDK for QuickSearch event log storage system
+Project-URL: Homepage, https://github.com/quicksearch/quicksearch-python-sdk
+Project-URL: Repository, https://github.com/quicksearch/quicksearch-python-sdk
+Project-URL: Issues, https://github.com/quicksearch/quicksearch-python-sdk/issues
+Author: QuickSearch Team
+License: MIT
+License-File: LICENSE
+Keywords: api-client,events,logging,search,syslog
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.11.7
+Provides-Extra: dev
+Requires-Dist: black>=24.10.0; extra == 'dev'
+Requires-Dist: mypy>=1.19.1; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
+Requires-Dist: pytest>=8.4.0; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Requires-Dist: ruff>=0.13.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# QuickSearch Python SDK
+
+[![PyPI version](https://badge.fury.io/py/quicksearch-python-sdk.svg)](https://badge.fury.io/py/quicksearch-python-sdk)
+[![Python versions](https://img.shields.io/pypi/pyversions/quicksearch-python-sdk.svg)](https://pypi.org/project/quicksearch-python-sdk/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Python library for interacting with the QuickSearch event log storage system.
+
+## Features
+
+- **Simple API**: Clean, pythonic interface for event ingestion and search
+- **Type Safety**: Full type hints and Pydantic models for data validation
+- **Async Support**: Both synchronous and asynchronous clients included
+- **Error Handling**: Comprehensive exception classes for easy error handling
+- **Flexible Authentication**: Support for API keys and JWT tokens
+
+## Installation
+
+```bash
+# Using uv
+uv add quicksearch-python-sdk
+
+# Using pip
+pip install quicksearch-python-sdk
+```
+
+## Quick Start
+
+### Synchronous Client
+
+```python
+from quicksearch import QuickSearchClient, EventData
+
+# Initialize client
+client = QuickSearchClient(
+    base_url="http://localhost:3000",
+    api_key="your-api-key-here"
+)
+
+# Ingest an event
+event = EventData(
+    type="user_login",
+    application="web_app",
+    data={"user_id": "12345", "ip_address": "192.168.1.100"}
+)
+
+response = client.ingest_event(event)
+print(f"Event ID: {response.eventId}")
+
+# Search for events
+result = client.search_events(query="login", limit=10)
+for event in result.events:
+    print(f"{event['timestamp_iso']}: {event['message']}")
+
+# Cleanup
+client.close()
+```
+
+### Using Context Manager
+
+```python
+from quicksearch import QuickSearchClient, EventData
+
+with QuickSearchClient(api_key="your-api-key") as client:
+    response = client.ingest_event(EventData(type="test_event"))
+    print(f"Success: {response.success}")
+```
+
+### Asynchronous Client
+
+```python
+import asyncio
+from quicksearch import AsyncQuickSearchClient, EventData
+
+async def main():
+    async with AsyncQuickSearchClient(api_key="your-api-key") as client:
+        # Ingest an event
+        event = EventData(type="user_login", data={"user_id": "12345"})
+        response = await client.ingest_event(event)
+        print(f"Event ID: {response.eventId}")
+
+        # Search for events
+        result = await client.search_events(query="login")
+        print(f"Found {result.count} events")
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### QuickSearchClient (Synchronous)
+
+#### Constructor
+
+```python
+QuickSearchClient(
+    base_url: str = "http://localhost:3000",
+    api_key: str | None = None,
+    jwt_token: str | None = None,
+    timeout: float = 30.0,
+    verify_ssl: bool = True
+)
+```
+
+#### Methods
+
+##### `ingest_event(event)`
+
+Ingest a single event.
+
+**Parameters:**
+- `event` (EventData | dict): Event data
+
+**Returns:** `EventResponse`
+
+**Example:**
+```python
+event = EventData(
+    type="user_login",
+    application="web_app",
+    message="User logged in",
+    data={"user_id": "12345"}
+)
+response = client.ingest_event(event)
+```
+
+##### `ingest_events(events)`
+
+Ingest multiple events in batch.
+
+**Parameters:**
+- `events` (list[EventData] | list[dict]): List of event data
+
+**Returns:** `list[EventResponse]`
+
+**Example:**
+```python
+events = [
+    EventData(type="click", data={"button": "submit"}),
+    EventData(type="view", data={"page": "home"}),
+]
+responses = client.ingest_events(events)
+```
+
+##### `search_events(**kwargs)`
+
+Search for events.
+
+**Parameters:**
+- `query` (str | None): Search query string
+- `limit` (int): Maximum results (default: 100)
+- `source` (str | None): Filter by source
+- `severity` (str | None): Filter by severity
+- `timestamp_gte` (str | None): Filter by timestamp (ISO format)
+
+**Returns:** `EventSearchResult`
+
+**Example:**
+```python
+result = client.search_events(
+    query="error",
+    source="syslog",
+    severity="critical",
+    limit=50
+)
+print(f"Found {result.count} events")
+for event in result.events:
+    print(event)
+```
+
+##### `ingest_syslog(syslog_data)`
+
+Ingest a syslog message.
+
+**Parameters:**
+- `syslog_data` (SyslogData | str | dict): Syslog data or raw string
+
+**Returns:** `EventResponse`
+
+**Example:**
+```python
+# Structured syslog
+from quicksearch import SyslogData
+
+syslog = SyslogData(
+    severity="error",
+    hostname="web-server-01",
+    message="Authentication failed",
+    data={"user": "admin"}
+)
+response = client.ingest_syslog(syslog)
+
+# Raw syslog string
+raw_syslog = "<34>Oct 11 22:14:15 mymachine su: 'su root' failed for user"
+response = client.ingest_syslog(raw_syslog)
+```
+
+### AsyncQuickSearchClient (Asynchronous)
+
+The async client has the same methods as the sync client, but all methods are async.
+
+```python
+async with AsyncQuickSearchClient(api_key="your-api-key") as client:
+    response = await client.ingest_event(EventData(type="test"))
+    result = await client.search_events(query="test")
+```
+
+## Data Models
+
+### EventData
+
+```python
+EventData(
+    type: str,                              # Required
+    application: str | None = None,
+    timestamp: str | None = None,           # ISO 8601 format
+    message: str | None = None,
+    data: dict[str, Any] = {},
+    source: str | None = None
+)
+```
+
+### SyslogData
+
+```python
+SyslogData(
+    type: str | None = None,
+    severity: str | None = None,
+    hostname: str | None = None,
+    message: str | None = None,
+    data: dict[str, Any] = {}
+)
+```
+
+### EventResponse
+
+```python
+EventResponse(
+    success: bool,
+    message: str,
+    eventId: str | None = None
+)
+```
+
+### EventSearchResult
+
+```python
+EventSearchResult(
+    success: bool,
+    events: list[dict[str, Any]],
+    count: int,
+    estimated_total: int | None = None,
+    processing_time_ms: int | None = None,
+    query: str | None = None
+)
+```
+
+## Error Handling
+
+The SDK provides specific exception types for different error scenarios:
+
+```python
+from quicksearch import (
+    QuickSearchClient,
+    EventData,
+    AuthenticationError,
+    PermissionError,
+    ValidationError,
+    RateLimitError,
+    ServerError,
+    ConnectionError
+)
+
+client = QuickSearchClient(api_key="your-api-key")
+
+try:
+    response = client.ingest_event(EventData(type="test"))
+except AuthenticationError:
+    print("Invalid API key or token")
+except PermissionError:
+    print("API key lacks required permission")
+except ValidationError as e:
+    print(f"Invalid data: {e}")
+except RateLimitError:
+    print("Daily API limit exceeded")
+except ServerError:
+    print("Server error occurred")
+except ConnectionError:
+    print("Failed to connect to server")
+```
+
+## Authentication
+
+### API Key Authentication
+
+```python
+# Via Authorization header (default)
+client = QuickSearchClient(api_key="your-api-key")
+```
+
+### JWT Token Authentication
+
+```python
+client = QuickSearchClient(jwt_token="your-jwt-token")
+```
+
+## Testing
+
+The SDK includes comprehensive tests. To run them:
+
+```bash
+# Install development dependencies
+uv sync --all-extras
+
+# Run tests
+uv run pytest
+
+# Run tests with coverage
+uv run pytest --cov=quicksearch --cov-report=html
+```
+
+## Development
+
+```bash
+# Install development dependencies
+uv sync --all-extras
+
+# Format code
+uv run black quicksearch tests
+
+# Lint code
+uv run ruff check quicksearch tests
+
+# Type check
+uv run mypy quicksearch
+```
+
+## Requirements
+
+- Python 3.9 or higher
+- requests >= 2.31.0
+- httpx >= 0.25.0
+- pydantic >= 2.5.0
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+For issues and questions, please visit the [GitHub repository](https://github.com/quicksearch/quicksearch-python-sdk).