| Name | pocketbase-orm JSON |
| Version |
0.13.2
JSON |
| download |
| home_page | None |
| Summary | Add your description here |
| upload_time | 2025-02-10 19:32:31 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# PocketBase ORM
A Python ORM (Object-Relational Mapper) for PocketBase that provides Pydantic model integration and automatic schema synchronization.
## Features
- 🚀 Pydantic model integration for data validation and serialization
- 🔄 Automatic schema synchronization with PocketBase collections
- 📦 Support for most PocketBase field types including relations and file uploads
- 🛠️ Simple and intuitive API for CRUD operations
## Installation
```bash
uv install pocketbase-orm
```
## Quick Start
```python
from pocketbase_orm import PBModel
from pydantic import EmailStr, AnyUrl, Field
from datetime import datetime, timezone
from pocketbase.client import FileUpload
# Define your models
class RelatedModel(PBModel, collection="related_models"): # Optionally specify collection name
name: str
class Example(PBModel): # Collection name will be "examples" by default
text_field: str
number_field: int
is_active: bool
url_field: AnyUrl
created_at: datetime
options: list[str]
email_field: EmailStr | None = None
related_model: RelatedModel | str = Field(..., description="Related model reference")
image: FileUpload | str = Field(..., description="Image file upload")
# Initialize PocketBase client and bind it to the ORM
client = PBModel.init_client(
"YOUR_POCKETBASE_URL",
"admin@example.com",
"password"
)
# Sync collection schemas
RelatedModel.sync_collection()
Example.sync_collection()
# Create and save records
related_model = RelatedModel(name="Related Model")
related_model.save()
# Create a new record with file upload
with open("image.png", "rb") as f:
example = Example(
text_field="Test with image",
number_field=123,
is_active=True,
email_field="test@example.com",
url_field="http://example.com",
created_at=datetime.now(timezone.utc),
options=["option1", "option2"],
related_model=related_model.id,
image=FileUpload(("image.png", f))
)
example.save()
# Query records
examples = Example.get_full_list()
single_example = Example.get_one("RECORD_ID")
filtered_example = Example.get_first_list_item(filter='email_field = "test@example.com"')
# Get file contents
image_bytes = example.get_file_contents("image")
```
## Model Definition
Models inherit from `PBModel` and use Pydantic field types:
```python
from enum import Enum
class UserType(str, Enum):
ADMIN = "admin"
REGULAR = "regular"
GUEST = "guest"
class MyModel(PBModel, collection="my_models"): # Specify custom collection name
name: str
age: int
email: EmailStr | None = None
user_type: UserType # Will be created as a select field in PocketBase
```
The collection name will be automatically derived from the class name (pluralized) if not specified using the `collection` parameter when subclassing `PBModel`.
## Supported Field Types
- Text: `str`
- Number: `int`, `float`
- Boolean: `bool`
- Email: `EmailStr`
- URL: `AnyUrl`
- DateTime: `datetime`
- JSON: `List`, `Dict`
- File: `FileUpload | str`
- Relation: `Union[RelatedModel, str]`
- Select: `Enum`
## API Reference
### Class Methods
- `bind_client(client: PocketBase)`: Bind PocketBase client to the model class
- `sync_collection()`: Create or update the collection schema in PocketBase
- `delete_collection()`: Delete the entire collection from PocketBase
- `get_one(id: str, **kwargs) -> T`: Get a single record by ID
- `get_list(*args, **kwargs) -> List[T]`: Get a paginated list of records
- `get_full_list(*args, **kwargs) -> List[T]`: Get all records
- `get_first_list_item(*args, **kwargs) -> T`: Get the first matching record
- `delete_by_id(id: str, **kwargs)`: Delete a record by ID
### Instance Methods
- `save() -> T`: Create or update the record
- `delete()`: Delete the current record
- `get_file_contents(field: str) -> bytes`: Get the contents of a file field
## Limitations
- The ORM currently supports basic CRUD operations and schema synchronization
- Complex queries should use the PocketBase client directly
- Relationship handling is limited to single relations
- Indexes must be created manually
- Schemas need to be updated manually until [this issue](https://github.com/vaphes/pocketbase/issues/117) is resolved
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "pocketbase-orm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/cd/66/a2b72b70e17ad3a26967404186d425706af691c6bb7b87d9693b5fb6b82b/pocketbase_orm-0.13.2.tar.gz",
"platform": null,
"description": "# PocketBase ORM\n\nA Python ORM (Object-Relational Mapper) for PocketBase that provides Pydantic model integration and automatic schema synchronization.\n\n## Features\n\n- \ud83d\ude80 Pydantic model integration for data validation and serialization\n- \ud83d\udd04 Automatic schema synchronization with PocketBase collections\n- \ud83d\udce6 Support for most PocketBase field types including relations and file uploads\n- \ud83d\udee0\ufe0f Simple and intuitive API for CRUD operations\n\n## Installation\n\n```bash\nuv install pocketbase-orm\n```\n\n## Quick Start\n\n```python\nfrom pocketbase_orm import PBModel\nfrom pydantic import EmailStr, AnyUrl, Field\nfrom datetime import datetime, timezone\nfrom pocketbase.client import FileUpload\n\n# Define your models\nclass RelatedModel(PBModel, collection=\"related_models\"): # Optionally specify collection name\n name: str\n\nclass Example(PBModel): # Collection name will be \"examples\" by default\n text_field: str\n number_field: int\n is_active: bool\n url_field: AnyUrl\n created_at: datetime\n options: list[str]\n email_field: EmailStr | None = None\n related_model: RelatedModel | str = Field(..., description=\"Related model reference\")\n image: FileUpload | str = Field(..., description=\"Image file upload\")\n\n# Initialize PocketBase client and bind it to the ORM\nclient = PBModel.init_client(\n \"YOUR_POCKETBASE_URL\",\n \"admin@example.com\",\n \"password\"\n)\n\n# Sync collection schemas\nRelatedModel.sync_collection()\nExample.sync_collection()\n\n# Create and save records\nrelated_model = RelatedModel(name=\"Related Model\")\nrelated_model.save()\n\n# Create a new record with file upload\nwith open(\"image.png\", \"rb\") as f:\n example = Example(\n text_field=\"Test with image\",\n number_field=123,\n is_active=True,\n email_field=\"test@example.com\",\n url_field=\"http://example.com\",\n created_at=datetime.now(timezone.utc),\n options=[\"option1\", \"option2\"],\n related_model=related_model.id,\n image=FileUpload((\"image.png\", f))\n )\n example.save()\n\n# Query records\nexamples = Example.get_full_list()\nsingle_example = Example.get_one(\"RECORD_ID\")\nfiltered_example = Example.get_first_list_item(filter='email_field = \"test@example.com\"')\n\n# Get file contents\nimage_bytes = example.get_file_contents(\"image\")\n```\n\n## Model Definition\n\nModels inherit from `PBModel` and use Pydantic field types:\n\n```python\nfrom enum import Enum\n\nclass UserType(str, Enum):\n ADMIN = \"admin\"\n REGULAR = \"regular\"\n GUEST = \"guest\"\n\nclass MyModel(PBModel, collection=\"my_models\"): # Specify custom collection name\n name: str\n age: int\n email: EmailStr | None = None\n user_type: UserType # Will be created as a select field in PocketBase\n```\n\nThe collection name will be automatically derived from the class name (pluralized) if not specified using the `collection` parameter when subclassing `PBModel`.\n\n## Supported Field Types\n\n- Text: `str`\n- Number: `int`, `float`\n- Boolean: `bool`\n- Email: `EmailStr`\n- URL: `AnyUrl`\n- DateTime: `datetime`\n- JSON: `List`, `Dict`\n- File: `FileUpload | str`\n- Relation: `Union[RelatedModel, str]`\n- Select: `Enum`\n\n## API Reference\n\n### Class Methods\n\n- `bind_client(client: PocketBase)`: Bind PocketBase client to the model class\n- `sync_collection()`: Create or update the collection schema in PocketBase\n- `delete_collection()`: Delete the entire collection from PocketBase\n- `get_one(id: str, **kwargs) -> T`: Get a single record by ID\n- `get_list(*args, **kwargs) -> List[T]`: Get a paginated list of records\n- `get_full_list(*args, **kwargs) -> List[T]`: Get all records\n- `get_first_list_item(*args, **kwargs) -> T`: Get the first matching record\n- `delete_by_id(id: str, **kwargs)`: Delete a record by ID\n\n### Instance Methods\n\n- `save() -> T`: Create or update the record\n- `delete()`: Delete the current record\n- `get_file_contents(field: str) -> bytes`: Get the contents of a file field\n\n## Limitations\n\n- The ORM currently supports basic CRUD operations and schema synchronization\n- Complex queries should use the PocketBase client directly\n- Relationship handling is limited to single relations\n- Indexes must be created manually\n- Schemas need to be updated manually until [this issue](https://github.com/vaphes/pocketbase/issues/117) is resolved\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Add your description here",
"version": "0.13.2",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8a948ea436b85df335689963dc632909da172d9151bc6719cf0008b703b380f8",
"md5": "c0e2e173152355a2a5726af99a19016f",
"sha256": "bb177e6bef4a640ddbfb1dd45726fb775df8958ecb456a5321f2b30419668b32"
},
"downloads": -1,
"filename": "pocketbase_orm-0.13.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c0e2e173152355a2a5726af99a19016f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 8627,
"upload_time": "2025-02-10T19:32:29",
"upload_time_iso_8601": "2025-02-10T19:32:29.970049Z",
"url": "https://files.pythonhosted.org/packages/8a/94/8ea436b85df335689963dc632909da172d9151bc6719cf0008b703b380f8/pocketbase_orm-0.13.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cd66a2b72b70e17ad3a26967404186d425706af691c6bb7b87d9693b5fb6b82b",
"md5": "0a410bf4d491a9f927fc644dfd8855e4",
"sha256": "4131efb4cc50adebf0dc83970f1f1db472d82b2141db79d4094a104db3a2e676"
},
"downloads": -1,
"filename": "pocketbase_orm-0.13.2.tar.gz",
"has_sig": false,
"md5_digest": "0a410bf4d491a9f927fc644dfd8855e4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 7741,
"upload_time": "2025-02-10T19:32:31",
"upload_time_iso_8601": "2025-02-10T19:32:31.735771Z",
"url": "https://files.pythonhosted.org/packages/cd/66/a2b72b70e17ad3a26967404186d425706af691c6bb7b87d9693b5fb6b82b/pocketbase_orm-0.13.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-10 19:32:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pocketbase-orm"
}
