[](https://github.com/roman-right/bosc)
# Bosc
[](https://pypi.python.org/pypi/bosc)
Bosc is a document store that provides an easy, Pythonic interface for handling documents stored on the local file system. It utilizes the full power of SQLite for storing and querying documents and employs Pydantic as the parsing and validation engine, ensuring it works seamlessly within the modern Python ecosystem, including FastAPI.
> ⚠️ Bosc is not an ORM for SQLite. It is a document-oriented store that uses SQLite as a backend. It is not designed to replace traditional SQL databases, but rather to provide a simple, Pythonic interface for working with flexible documents.
## Installation
Before you begin, ensure you have Python installed on your system. This document store requires Python 3.8 or newer.
You can install Bosc using pip:
```shell
pip install bosc
```
## Quickstart
### Defining a Document Model
```python
from bosc import Document
class User(Document):
name: str
age: int
# Specify the database path for this document
bosc_database_path = "my_database.db"
# Specify the collection name for this document (Optional)
bosc_collection_name = "users"
```
### Inserting Documents
```python
user = User(name="John Doe", age=30)
user.insert() # Insert the document into the database
# Inserting multiple documents
User.insert_many([
User(name="Jane Doe", age=25),
User(name="Alice", age=35),
])
```
### Querying Documents
```python
# Find all users
users = User.find()
# Find users with specific criteria
johns = User.find(User.name == "John Doe")
young_users = User.find(User.age < 30)
# Find users with multiple criteria
users = User.find(User.name == "John Doe", User.age > 30)
# Find having order by
users = User.find(
User.name == "John Doe",
order_by="age",
order_direction=OrderDirection.ASC
)
# Find with limit
users = User.find(User.name == "John Doe", limit=1)
# Find with offset
users = User.find(User.name == "John Doe", offset=1)
# Find a single user
jane = User.find_one(User.name == "Jane Doe")
```
### Updating Documents
```python
# Update all users named John Doe to have age 31
User.update(User.name == "John Doe", Set("age", 31))
# Update a single document
john = User.find_one(User.name == "John Doe")
john.age = 32
john.save() # This uses the OnConflict.REPLACE strategy
```
### Deleting Documents
```python
# Delete a specific user
jane.delete()
# Delete all users named Alice
User.delete_many(User.name == "Alice")
```
## Advanced Usage
### Working with Indexes
To improve query performance, you can define indexes on your document fields.
```python
from bosc import Document, Index, IndexType
class User(Document):
name: str
age: int
bosc_indexes = [
Index("name", IndexType.UNIQUE),
Index("age", IndexType.PATH),
]
bosc_database_path = "my_database.db"
# Sync indexes with the database
User.sync_indexes()
```
This will create indexes on the `name` and `age` fields of the `User` documents, assuming `Index` and `IndexType` are properly defined and imported from the `bosc` package.
### Complex Queries
Leverage the full power of queries with complex conditions and ordering.
```python
from bosc import And, Or
from bosc import OrderDirection
# Find users named John Doe over 30 years old
users = User.find(And(User.name == "John Doe", User.age > 30))
# Find users either named Alice or younger than 25
users = User.find(Or(User.name == "Alice", User.age < 25))
# Order users by age
users = User.find(order_by="age", order_direction=OrderDirection.ASC)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "bosc",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "document store, file-based, python, pydantic, sqlite",
"author": null,
"author_email": "Roman Right <roman-right@protonmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b3/34/fe9a483d31b59807cf9674bc36627ce304e156e046e31a46fd2ceedc7412/bosc-0.0.7.tar.gz",
"platform": null,
"description": "[](https://github.com/roman-right/bosc)\n\n# Bosc\n\n[](https://pypi.python.org/pypi/bosc)\n\nBosc is a document store that provides an easy, Pythonic interface for handling documents stored on the local file system. It utilizes the full power of SQLite for storing and querying documents and employs Pydantic as the parsing and validation engine, ensuring it works seamlessly within the modern Python ecosystem, including FastAPI.\n\n\n> \u26a0\ufe0f Bosc is not an ORM for SQLite. It is a document-oriented store that uses SQLite as a backend. It is not designed to replace traditional SQL databases, but rather to provide a simple, Pythonic interface for working with flexible documents.\n\n## Installation\nBefore you begin, ensure you have Python installed on your system. This document store requires Python 3.8 or newer.\n\nYou can install Bosc using pip:\n\n```shell\npip install bosc\n```\n\n## Quickstart\n\n### Defining a Document Model\n\n```python\nfrom bosc import Document\n\n\nclass User(Document):\n name: str\n age: int\n\n # Specify the database path for this document\n bosc_database_path = \"my_database.db\"\n \n # Specify the collection name for this document (Optional)\n bosc_collection_name = \"users\"\n```\n\n### Inserting Documents\n```python\nuser = User(name=\"John Doe\", age=30)\nuser.insert() # Insert the document into the database\n\n# Inserting multiple documents\nUser.insert_many([\n User(name=\"Jane Doe\", age=25),\n User(name=\"Alice\", age=35),\n])\n```\n\n### Querying Documents\n```python\n# Find all users\nusers = User.find()\n\n# Find users with specific criteria\njohns = User.find(User.name == \"John Doe\")\nyoung_users = User.find(User.age < 30)\n\n# Find users with multiple criteria\nusers = User.find(User.name == \"John Doe\", User.age > 30)\n\n# Find having order by\nusers = User.find(\n User.name == \"John Doe\", \n order_by=\"age\", \n order_direction=OrderDirection.ASC\n)\n\n# Find with limit\nusers = User.find(User.name == \"John Doe\", limit=1)\n\n# Find with offset\nusers = User.find(User.name == \"John Doe\", offset=1)\n\n# Find a single user\njane = User.find_one(User.name == \"Jane Doe\")\n```\n\n### Updating Documents\n```python\n# Update all users named John Doe to have age 31\nUser.update(User.name == \"John Doe\", Set(\"age\", 31))\n\n# Update a single document\njohn = User.find_one(User.name == \"John Doe\")\njohn.age = 32\njohn.save() # This uses the OnConflict.REPLACE strategy\n```\n\n### Deleting Documents\n```python\n# Delete a specific user\njane.delete()\n\n# Delete all users named Alice\nUser.delete_many(User.name == \"Alice\")\n```\n\n## Advanced Usage\n\n### Working with Indexes\nTo improve query performance, you can define indexes on your document fields.\n\n```python\nfrom bosc import Document, Index, IndexType\n\nclass User(Document):\n name: str\n age: int\n\n bosc_indexes = [\n Index(\"name\", IndexType.UNIQUE),\n Index(\"age\", IndexType.PATH),\n ]\n bosc_database_path = \"my_database.db\"\n\n# Sync indexes with the database\nUser.sync_indexes()\n```\n\nThis will create indexes on the `name` and `age` fields of the `User` documents, assuming `Index` and `IndexType` are properly defined and imported from the `bosc` package.\n\n### Complex Queries\nLeverage the full power of queries with complex conditions and ordering.\n\n```python\nfrom bosc import And, Or\nfrom bosc import OrderDirection\n\n# Find users named John Doe over 30 years old\nusers = User.find(And(User.name == \"John Doe\", User.age > 30))\n\n# Find users either named Alice or younger than 25\nusers = User.find(Or(User.name == \"Alice\", User.age < 25))\n\n# Order users by age\nusers = User.find(order_by=\"age\", order_direction=OrderDirection.ASC)\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A file-based document store with python interface",
"version": "0.0.7",
"project_urls": {
"repository": "https://github.com/roman-right/bosc"
},
"split_keywords": [
"document store",
" file-based",
" python",
" pydantic",
" sqlite"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e324990ccfcbf79d9bdd5284df6c1d4c44f64dafb050860c0a150ef966bbc2d6",
"md5": "2e47101b80fbbdb1c8e37fc6990c787a",
"sha256": "28a9b625ce6edc4f3fcabf90742a5fa3a2dec0cf1e233953f20014a248f1e655"
},
"downloads": -1,
"filename": "bosc-0.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2e47101b80fbbdb1c8e37fc6990c787a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 16563,
"upload_time": "2024-06-10T15:07:36",
"upload_time_iso_8601": "2024-06-10T15:07:36.596185Z",
"url": "https://files.pythonhosted.org/packages/e3/24/990ccfcbf79d9bdd5284df6c1d4c44f64dafb050860c0a150ef966bbc2d6/bosc-0.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b334fe9a483d31b59807cf9674bc36627ce304e156e046e31a46fd2ceedc7412",
"md5": "c40611e105a1a4dea95f79ea1ede4b20",
"sha256": "c224fdf2bf6322cd36c7b4f56fdcee20d8f181269a9d5f21d8a48937123998a9"
},
"downloads": -1,
"filename": "bosc-0.0.7.tar.gz",
"has_sig": false,
"md5_digest": "c40611e105a1a4dea95f79ea1ede4b20",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 32571,
"upload_time": "2024-06-10T15:07:38",
"upload_time_iso_8601": "2024-06-10T15:07:38.186553Z",
"url": "https://files.pythonhosted.org/packages/b3/34/fe9a483d31b59807cf9674bc36627ce304e156e046e31a46fd2ceedc7412/bosc-0.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-10 15:07:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "roman-right",
"github_project": "bosc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "bosc"
}
JSON
