# GitDB Python SDK
Official Python client for GitDB - GitHub-backed NoSQL database.
## Features
- 🚀 **Easy to use** - Familiar MongoDB-like API
- 🔗 **Connection management** - Automatic reconnection and health checks
- 📊 **GraphQL support** - Full GraphQL client with introspection
- 🔒 **Type safety** - Full type hints and Pydantic models
- ⚡ **Async support** - Modern async/await API
- 🛡️ **Error handling** - Comprehensive error types and handling
- 🔧 **Flexible configuration** - Environment variables and custom config
## Installation
```bash
pip install gitdb-client
```
## Quick Start
### Basic Usage
```python
import asyncio
from gitdb import GitDB
async def main():
# Initialize client
db = GitDB.from_environment()
# Connect and use
await db.connect()
users = db.collection('users')
# Insert a document
user = await users.insert({
'name': 'John Doe',
'email': 'john@example.com',
'age': 30
})
# Find documents
all_users = await users.find()
john = await users.find_one({'name': 'John Doe'})
# Update document
await users.update(user['document']['_id'], {'age': 31})
# Delete document
await users.delete(user['document']['_id'])
await db.disconnect()
# Run the example
asyncio.run(main())
```
### Environment Variables
```python
import os
# Set environment variables
os.environ['GITDB_TOKEN'] = 'ghp_your_github_token_here'
os.environ['GITDB_OWNER'] = 'your-username'
os.environ['GITDB_REPO'] = 'your-database-repo'
os.environ['GITDB_HOST'] = 'localhost'
os.environ['GITDB_PORT'] = '7896'
# Use from environment
db = GitDB.from_environment()
```
## API Reference
### GitDB Client
#### Constructor
```python
GitDB(config: GitDBConfig)
```
**Config Options:**
- `token` (required): GitHub personal access token
- `owner` (required): GitHub username or organization
- `repo` (required): GitHub repository name
- `host` (optional): GitDB server host (default: 'localhost')
- `port` (optional): GitDB server port (default: 7896)
- `timeout` (optional): Request timeout in ms (default: 30000)
- `retries` (optional): Number of retry attempts (default: 3)
#### Methods
```python
# Connection management
await db.connect(): None
await db.disconnect(): None
db.is_connected(): bool
await db.get_status(): ConnectionStatus
await db.ping(): bool
await db.health(): Any
# Collection management
db.collection(name: str): Collection
await db.list_collections(): List[str]
await db.create_collection(name: str): None
await db.delete_collection(name: str): None
# Utility methods
await db.use_collection(name: str): Collection
# Static methods
GitDB.from_environment(): GitDB
GitDB.from_config(config: GitDBConfig): GitDB
```
### Collection API
#### Methods
```python
# Create operations
await collection.insert(document: Dict[str, Any]): Dict[str, Any]
# Read operations
await collection.find(query: Optional[Dict[str, Any]] = None): Dict[str, Any]
await collection.find_one(query: Optional[Dict[str, Any]] = None): Optional[Dict[str, Any]]
await collection.find_by_id(id: str): Optional[Dict[str, Any]]
await collection.count(query: Optional[Dict[str, Any]] = None): int
# Update operations
await collection.update(id: str, update: Dict[str, Any]): Dict[str, Any]
# Delete operations
await collection.delete(id: str): Dict[str, Any]
```
## Examples
See the `examples/` directory for complete working examples:
- `basic_test.py` - Basic connection and operations
- `crud_test.py` - CRUD operations
- `graphql_test.py` - GraphQL queries and mutations
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/karthikeyanV2K/GitDB",
"name": "gitdb-client",
"maintainer": "karthikeyanV2K",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "karthikeyan@afot.com",
"keywords": "gitdb, database, nosql, github, client, sdk, python, async",
"author": "AFOT Team",
"author_email": "team@afot.com",
"download_url": "https://files.pythonhosted.org/packages/8d/6a/21d133af783cf634ba7cd3ca6d99b5b2d1faa8425fa9ab0580f2c26a3754/gitdb_client-1.0.0.tar.gz",
"platform": null,
"description": "# GitDB Python SDK\r\n\r\nOfficial Python client for GitDB - GitHub-backed NoSQL database.\r\n\r\n## Features\r\n\r\n- \ud83d\ude80 **Easy to use** - Familiar MongoDB-like API\r\n- \ud83d\udd17 **Connection management** - Automatic reconnection and health checks\r\n- \ud83d\udcca **GraphQL support** - Full GraphQL client with introspection\r\n- \ud83d\udd12 **Type safety** - Full type hints and Pydantic models\r\n- \u26a1 **Async support** - Modern async/await API\r\n- \ud83d\udee1\ufe0f **Error handling** - Comprehensive error types and handling\r\n- \ud83d\udd27 **Flexible configuration** - Environment variables and custom config\r\n\r\n## Installation\r\n\r\n```bash\r\npip install gitdb-client\r\n```\r\n\r\n## Quick Start\r\n\r\n### Basic Usage\r\n\r\n```python\r\nimport asyncio\r\nfrom gitdb import GitDB\r\n\r\nasync def main():\r\n # Initialize client\r\n db = GitDB.from_environment()\r\n \r\n # Connect and use\r\n await db.connect()\r\n \r\n users = db.collection('users')\r\n \r\n # Insert a document\r\n user = await users.insert({\r\n 'name': 'John Doe',\r\n 'email': 'john@example.com',\r\n 'age': 30\r\n })\r\n \r\n # Find documents\r\n all_users = await users.find()\r\n john = await users.find_one({'name': 'John Doe'})\r\n \r\n # Update document\r\n await users.update(user['document']['_id'], {'age': 31})\r\n \r\n # Delete document\r\n await users.delete(user['document']['_id'])\r\n \r\n await db.disconnect()\r\n\r\n# Run the example\r\nasyncio.run(main())\r\n```\r\n\r\n### Environment Variables\r\n\r\n```python\r\nimport os\r\n\r\n# Set environment variables\r\nos.environ['GITDB_TOKEN'] = 'ghp_your_github_token_here'\r\nos.environ['GITDB_OWNER'] = 'your-username'\r\nos.environ['GITDB_REPO'] = 'your-database-repo'\r\nos.environ['GITDB_HOST'] = 'localhost'\r\nos.environ['GITDB_PORT'] = '7896'\r\n\r\n# Use from environment\r\ndb = GitDB.from_environment()\r\n```\r\n\r\n## API Reference\r\n\r\n### GitDB Client\r\n\r\n#### Constructor\r\n\r\n```python\r\nGitDB(config: GitDBConfig)\r\n```\r\n\r\n**Config Options:**\r\n- `token` (required): GitHub personal access token\r\n- `owner` (required): GitHub username or organization\r\n- `repo` (required): GitHub repository name\r\n- `host` (optional): GitDB server host (default: 'localhost')\r\n- `port` (optional): GitDB server port (default: 7896)\r\n- `timeout` (optional): Request timeout in ms (default: 30000)\r\n- `retries` (optional): Number of retry attempts (default: 3)\r\n\r\n#### Methods\r\n\r\n```python\r\n# Connection management\r\nawait db.connect(): None\r\nawait db.disconnect(): None\r\ndb.is_connected(): bool\r\nawait db.get_status(): ConnectionStatus\r\nawait db.ping(): bool\r\nawait db.health(): Any\r\n\r\n# Collection management\r\ndb.collection(name: str): Collection\r\nawait db.list_collections(): List[str]\r\nawait db.create_collection(name: str): None\r\nawait db.delete_collection(name: str): None\r\n\r\n# Utility methods\r\nawait db.use_collection(name: str): Collection\r\n\r\n# Static methods\r\nGitDB.from_environment(): GitDB\r\nGitDB.from_config(config: GitDBConfig): GitDB\r\n```\r\n\r\n### Collection API\r\n\r\n#### Methods\r\n\r\n```python\r\n# Create operations\r\nawait collection.insert(document: Dict[str, Any]): Dict[str, Any]\r\n\r\n# Read operations\r\nawait collection.find(query: Optional[Dict[str, Any]] = None): Dict[str, Any]\r\nawait collection.find_one(query: Optional[Dict[str, Any]] = None): Optional[Dict[str, Any]]\r\nawait collection.find_by_id(id: str): Optional[Dict[str, Any]]\r\nawait collection.count(query: Optional[Dict[str, Any]] = None): int\r\n\r\n# Update operations\r\nawait collection.update(id: str, update: Dict[str, Any]): Dict[str, Any]\r\n\r\n# Delete operations\r\nawait collection.delete(id: str): Dict[str, Any]\r\n```\r\n\r\n## Examples\r\n\r\nSee the `examples/` directory for complete working examples:\r\n\r\n- `basic_test.py` - Basic connection and operations\r\n- `crud_test.py` - CRUD operations\r\n- `graphql_test.py` - GraphQL queries and mutations\r\n\r\n## Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch\r\n3. Make your changes\r\n4. Add tests\r\n5. Submit a pull request\r\n\r\n## License\r\n\r\nMIT License - see LICENSE file for details. \r\n",
"bugtrack_url": null,
"license": null,
"summary": "Official Python client for GitDB - GitHub-backed NoSQL database",
"version": "1.0.0",
"project_urls": {
"Bug Reports": "https://github.com/karthikeyanV2K/GitDB/issues",
"Documentation": "https://github.com/karthikeyanV2K/GitDB/tree/main/sdk/python",
"Homepage": "https://github.com/karthikeyanV2K/GitDB",
"Source": "https://github.com/karthikeyanV2K/GitDB"
},
"split_keywords": [
"gitdb",
" database",
" nosql",
" github",
" client",
" sdk",
" python",
" async"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f9b88e3e85579991be452f37a961eb768d31a23a8e1cf2a00a3819af222c8b21",
"md5": "7c2fb67f16848097d042361c9c7d2891",
"sha256": "91b0936b5021817b35e1157e28ddddfe7af41dbf82522793e34d4ae995b117fd"
},
"downloads": -1,
"filename": "gitdb_client-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c2fb67f16848097d042361c9c7d2891",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8716,
"upload_time": "2025-07-12T15:52:27",
"upload_time_iso_8601": "2025-07-12T15:52:27.730629Z",
"url": "https://files.pythonhosted.org/packages/f9/b8/8e3e85579991be452f37a961eb768d31a23a8e1cf2a00a3819af222c8b21/gitdb_client-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8d6a21d133af783cf634ba7cd3ca6d99b5b2d1faa8425fa9ab0580f2c26a3754",
"md5": "dd1c5daa300622ed31f9e7679427f850",
"sha256": "e7c178d44dd854dbe9e7217396bdaad389d9c9c5685ea4a12830a5c6875b9f77"
},
"downloads": -1,
"filename": "gitdb_client-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "dd1c5daa300622ed31f9e7679427f850",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 9631,
"upload_time": "2025-07-12T15:52:28",
"upload_time_iso_8601": "2025-07-12T15:52:28.971033Z",
"url": "https://files.pythonhosted.org/packages/8d/6a/21d133af783cf634ba7cd3ca6d99b5b2d1faa8425fa9ab0580f2c26a3754/gitdb_client-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-12 15:52:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "karthikeyanV2K",
"github_project": "GitDB",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gitdb-client"
}
JSON
