| Name | ormdantic JSON |
| Version |
1.7.0
JSON |
| download |
| home_page | None |
| Summary | asynchronous ORM that uses pydantic models to represent database tables |
| upload_time | 2024-04-19 04:16:19 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
asyncio
orm
pydantic
sqlalchemy
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<em>Asynchronous ORM that uses pydantic models to represent database tables ✨</em>
</p>
<p align="center">
<a href="https://github.com/yezz123/ormdantic/actions/workflows/ci.yml" target="_blank">
<img src="https://github.com/yezz123/ormdantic/actions/workflows/ci.yml/badge.svg" alt="Test">
</a>
<a href="https://codecov.io/gh/yezz123/ormdantic">
<img src="https://codecov.io/gh/yezz123/ormdantic/branch/main/graph/badge.svg"/>
</a>
<a href="https://pypi.org/project/ormdantic" target="_blank">
<img src="https://img.shields.io/pypi/v/ormdantic?color=%2334D058&label=pypi%20package" alt="Package version">
</a>
<a href="https://pypi.org/project/ormdantic" target="_blank">
<img src="https://img.shields.io/pypi/pyversions/ormdantic.svg?color=%2334D058" alt="Supported Python versions">
</a>
</p>
Ormdantic is a library for interacting with Asynchronous <abbr title='Also called "Relational databases"'>SQL databases</abbr> from Python code, with Python objects. It is designed to be intuitive, easy to use, compatible, and robust.
**Ormdantic** is based on [Pypika](https://github.com/kayak/pypika), and powered by <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a> and <a href="https://sqlalchemy.org/" class="external-link" target="_blank">SQLAlchemy</a>, and Highly inspired by <a href="https://github.com/tiangolo/Sqlmodel" class="external-link" target="_blank">Sqlmodel</a>, Created by [@tiangolo](https://github.com/tiangolo).
> What is [Pypika](https://github.com/kayak/pypika)?
>
> PyPika is a Python API for building SQL queries. The motivation behind PyPika is to provide a simple interface for building SQL queries without limiting the flexibility of handwritten SQL. Designed with data analysis in mind, PyPika leverages the builder design pattern to construct queries to avoid messy string formatting and concatenation. It is also easily extended to take full advantage of specific features of SQL database vendors.
The key features are:
* **Easy to use**: It has sensible defaults and does a lot of work underneath to simplify the code you write.
* **Compatible**: It combines SQLAlchemy, Pydantic and Pypika tries to simplify the code you write as much as possible, allowing you to reduce the code duplication to a minimum, but while getting the best developer experience possible.
* **Extensible**: You have all the power of SQLAlchemy and Pypika underneath.
* **Short Queries**: You can write queries in a single line of code, and it will be converted to the appropriate syntax for the database you are using.
## Requirements
A recent and currently supported version of Python (right now, <a href="https://www.python.org/downloads/" class="external-link" target="_blank">Python supports versions 3.10 and above</a>).
As **Ormdantic** is based on **Pydantic** and **SQLAlchemy** and **Pypika**, it requires them. They will be automatically installed when you install Ormdantic.
## Installation
You can add Ormdantic in a few easy steps. First of all, install the dependency:
```shell
$ pip install ormdantic
---> 100%
Successfully installed Ormdantic
```
* Install The specific Asynchronous ORM library for your database.
```shell
# PostgreSQL
$ pip install ormdantic[postgres]
# SQLite
$ pip install ormdantic[sqlite]
```
## Example
To understand SQL, Sebastian the Creator of FastAPI and SQLModel created an amazing documentation that could help you understand the basics of SQL, ex. `CREATE TABLE`, `INSERT`, `SELECT`, `UPDATE`, `DELETE`, etc.
Check out the [documentation](https://sqlmodel.tiangolo.com/).
But let's see how to use Ormdantic.
### Create SQLAlchemy engine
Ormdantic uses SQLAlchemy under hood to run different queries, which is why we need to initialize by creating an asynchronous engine.
> **Note**: You will use the `connection` parameter to pass the connection to the engine directly.
```python
from ormdantic import Ormdantic
connection = "sqlite+aiosqlite:///db.sqlite3"
database = Ormdantic(connection)
```
**Note**: You can use any asynchronous engine, check out the [documentation](https://docs.sqlalchemy.org/en/14/core/engines.html) for more information.
### Create a table
To create tables decorate a pydantic model with the `database.table` decorator, passing the database information ex. `Primary key`, `foreign keys`, `Indexes`, `back_references`, `unique_constraints` etc. to the decorator call.
#### Table Restrictions
* Tables must have a single column primary key.
* The primary key column must be the first column.
* Relationships must `union-type` the foreign model and that models primary key.
```python
from uuid import uuid4
from pydantic import BaseModel, Field
@database.table(pk="id", indexed=["name"])
class Flavor(BaseModel):
"""A coffee flavor."""
id: UUID = Field(default_factory=uuid4)
name: str = Field(max_length=63)
```
### Queries
Now after we create the table, we can initialize the database with the table and then run different queries.
#### Init()
* Register models as ORM models and initialize the database.
We use `database.init` will Populate relations information and create the tables.
```python
async def demo() -> None:
async def _init() -> None:
async with db._engine.begin() as conn:
await db.init()
await conn.run_sync(db._metadata.drop_all)
await conn.run_sync(db._metadata.create_all)
await _init()
```
#### Insert
Now let's imagine we have another table called `Coffee` that has a foreign key to `Flavor`.
```python
@database.table(pk="id")
class Coffee(BaseModel):
"""Drink it in the morning."""
id: UUID = Field(default_factory=uuid4)
sweetener: str | None = Field(max_length=63)
sweetener_count: int | None = None
flavor: Flavor | UUID
```
After we create the table, we can insert data into the table, using the `database.insert` method, is away we insert a Model Instance.
```python
# Create a Flavor called "Vanilla"
vanilla = Flavor(name="Vanilla")
# Insert the Flavor into the database
await database[Flavor].insert(vanilla)
# Create a Coffee with the Vanilla Flavor
coffee = Coffee(sweetener="Sugar", sweetener_count=1, flavor=vanilla)
# Insert the Coffee into the database
await database[Coffee].insert(coffee)
```
#### Searching Queries
As we know, in SQL, we can search for data using different methods, ex. `WHERE`, `LIKE`, `IN`, `BETWEEN`, etc.
In Ormdantic, we can search for data using the `database.find_one` or `database.find_many` methods.
* `Find_one` used to find a Model instance by Primary Key, its could also find with `depth` parameter.
```python
# Find one
vanilla = await database[Flavor].find_one(flavor.id)
print(vanilla.name)
# Find one with depth.
find_coffee = await database[Coffee].find_one(coffee.id, depth=1)
print(find_coffee.flavor.name)
```
* `Find_many` used to find Model instances by some condition ex. `where`, `order_by`, `order`, `limit`, `offset`, `depth`.
```python
# Find many
await database[Flavor].find_many()
# Get paginated results.
await database[Flavor].find_many(
where={"name": "vanilla"}, order_by=["id", "name"], limit=2, offset=2
)
```
#### Update / Upsert Queries
##### Update
The modification of data that is already in the database is referred to as updating. You can update individual rows, all the rows in a table, or a subset of all rows. Each column can be updated separately; the other columns are not affected.
```python
# Update a Flavor
flavor.name = "caramel"
await database[Flavor].update(flavor)
```
##### Upsert
The `Upsert` method is similar to the Synchronize method with one exception; the `Upsert` method does not delete any records. The `Upsert` method will result in insert or update operations. If the record exists, it will be updated. If the record does not exist, it will be inserted.
```python
# Upsert a Flavor
flavor.name = "mocha"
await database[Flavor].upsert(flavor)
```
### Delete
The `DELETE` statement is used to delete existing records in a table.
```python
# Delete a Flavor
await database[Flavor].delete(flavor.id)
```
### Count
To count the number of rows of a table or in a result set you can use the `count` function.
```python
# Count
count = await database[Flavor].count()
print(count)
```
* It's support also `Where` and `Depth`
```python
count_advanced = await database[Coffee].count(
where={"sweetener": 2}, depth=1
)
print(count_advanced)
```
## Generator Feature
We introduce a new feature called `Generator`, which is a way to generate a Model instance with random data.
So, Given a Pydantic model type can generate instances of that model with randomly generated values.
using `ormdantic.generator.Generator` to generate a Model instance.
```python
from enum import auto, Enum
from uuid import UUID
from ormdantic.generator import Generator
from pydantic import BaseModel
class Flavor(Enum):
MOCHA = auto()
VANILLA = auto()
class Brand(BaseModel):
brand_name: str
class Coffee(BaseModel):
id: UUID
description: str
cream: bool
sweetener: int
flavor: Flavor
brand: Brand
print(Generator(Coffee))
```
so the results will be:
```shell
id=UUID('93b517c2-083b-457d-a0e5-6e1bd2a927e4')
description='ctWOb' cream=True sweetener=234
flavor=<Flavor.VANILLA: 2> brand=Brand(brand_name='LMrIf')
```
We can integrate this with our database while testing our application (Live Tests).
## Development 🚧
### Setup environment 📦
You should create a virtual environment and activate it:
```bash
python -m venv venv/
```
```bash
source venv/bin/activate
```
And then install the development dependencies:
```bash
# Install dependencies
pip install -r requirements/all.txt
```
### Run tests 🌝
You can run all the tests with:
```bash
bash scripts/test.sh
```
### Format the code 🍂
Execute the following command to apply `pre-commit` formatting:
```bash
bash scripts/format.sh
```
Execute the following command to apply `mypy` type checking:
```bash
bash scripts/lint.sh
```
## License
This project is licensed under the terms of the MIT license.
Raw data
{
"_id": null,
"home_page": null,
"name": "ormdantic",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "asyncio, orm, pydantic, sqlalchemy",
"author": null,
"author_email": "Yasser Tahiri <hello@yezz.me>",
"download_url": "https://files.pythonhosted.org/packages/32/1c/9b67fe417b6ae18e67ec429f8c9a5a5b7aa9e8ec2f784a1b97bbb03394ee/ormdantic-1.7.0.tar.gz",
"platform": null,
"description": "\n\n<p align=\"center\">\n <em>Asynchronous ORM that uses pydantic models to represent database tables \u2728</em>\n</p>\n\n<p align=\"center\">\n<a href=\"https://github.com/yezz123/ormdantic/actions/workflows/ci.yml\" target=\"_blank\">\n <img src=\"https://github.com/yezz123/ormdantic/actions/workflows/ci.yml/badge.svg\" alt=\"Test\">\n</a>\n<a href=\"https://codecov.io/gh/yezz123/ormdantic\">\n <img src=\"https://codecov.io/gh/yezz123/ormdantic/branch/main/graph/badge.svg\"/>\n</a>\n<a href=\"https://pypi.org/project/ormdantic\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/ormdantic?color=%2334D058&label=pypi%20package\" alt=\"Package version\">\n</a>\n<a href=\"https://pypi.org/project/ormdantic\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/pyversions/ormdantic.svg?color=%2334D058\" alt=\"Supported Python versions\">\n</a>\n</p>\n\nOrmdantic is a library for interacting with Asynchronous <abbr title='Also called \"Relational databases\"'>SQL databases</abbr> from Python code, with Python objects. It is designed to be intuitive, easy to use, compatible, and robust.\n\n**Ormdantic** is based on [Pypika](https://github.com/kayak/pypika), and powered by <a href=\"https://pydantic-docs.helpmanual.io/\" class=\"external-link\" target=\"_blank\">Pydantic</a> and <a href=\"https://sqlalchemy.org/\" class=\"external-link\" target=\"_blank\">SQLAlchemy</a>, and Highly inspired by <a href=\"https://github.com/tiangolo/Sqlmodel\" class=\"external-link\" target=\"_blank\">Sqlmodel</a>, Created by [@tiangolo](https://github.com/tiangolo).\n\n> What is [Pypika](https://github.com/kayak/pypika)?\n>\n> PyPika is a Python API for building SQL queries. The motivation behind PyPika is to provide a simple interface for building SQL queries without limiting the flexibility of handwritten SQL. Designed with data analysis in mind, PyPika leverages the builder design pattern to construct queries to avoid messy string formatting and concatenation. It is also easily extended to take full advantage of specific features of SQL database vendors.\n\nThe key features are:\n\n* **Easy to use**: It has sensible defaults and does a lot of work underneath to simplify the code you write.\n* **Compatible**: It combines SQLAlchemy, Pydantic and Pypika tries to simplify the code you write as much as possible, allowing you to reduce the code duplication to a minimum, but while getting the best developer experience possible.\n* **Extensible**: You have all the power of SQLAlchemy and Pypika underneath.\n* **Short Queries**: You can write queries in a single line of code, and it will be converted to the appropriate syntax for the database you are using.\n\n## Requirements\n\nA recent and currently supported version of Python (right now, <a href=\"https://www.python.org/downloads/\" class=\"external-link\" target=\"_blank\">Python supports versions 3.10 and above</a>).\n\nAs **Ormdantic** is based on **Pydantic** and **SQLAlchemy** and **Pypika**, it requires them. They will be automatically installed when you install Ormdantic.\n\n## Installation\n\nYou can add Ormdantic in a few easy steps. First of all, install the dependency:\n\n```shell\n$ pip install ormdantic\n\n---> 100%\n\nSuccessfully installed Ormdantic\n```\n\n* Install The specific Asynchronous ORM library for your database.\n\n```shell\n# PostgreSQL\n$ pip install ormdantic[postgres]\n\n# SQLite\n$ pip install ormdantic[sqlite]\n```\n\n## Example\n\nTo understand SQL, Sebastian the Creator of FastAPI and SQLModel created an amazing documentation that could help you understand the basics of SQL, ex. `CREATE TABLE`, `INSERT`, `SELECT`, `UPDATE`, `DELETE`, etc.\n\nCheck out the [documentation](https://sqlmodel.tiangolo.com/).\n\nBut let's see how to use Ormdantic.\n\n### Create SQLAlchemy engine\n\nOrmdantic uses SQLAlchemy under hood to run different queries, which is why we need to initialize by creating an asynchronous engine.\n\n> **Note**: You will use the `connection` parameter to pass the connection to the engine directly.\n\n```python\nfrom ormdantic import Ormdantic\n\nconnection = \"sqlite+aiosqlite:///db.sqlite3\"\n\ndatabase = Ormdantic(connection)\n```\n\n**Note**: You can use any asynchronous engine, check out the [documentation](https://docs.sqlalchemy.org/en/14/core/engines.html) for more information.\n\n### Create a table\n\nTo create tables decorate a pydantic model with the `database.table` decorator, passing the database information ex. `Primary key`, `foreign keys`, `Indexes`, `back_references`, `unique_constraints` etc. to the decorator call.\n\n#### Table Restrictions\n\n* Tables must have a single column primary key.\n* The primary key column must be the first column.\n* Relationships must `union-type` the foreign model and that models primary key.\n\n```python\nfrom uuid import uuid4\nfrom pydantic import BaseModel, Field\n\n@database.table(pk=\"id\", indexed=[\"name\"])\nclass Flavor(BaseModel):\n \"\"\"A coffee flavor.\"\"\"\n\n id: UUID = Field(default_factory=uuid4)\n name: str = Field(max_length=63)\n```\n\n### Queries\n\nNow after we create the table, we can initialize the database with the table and then run different queries.\n\n#### Init()\n\n* Register models as ORM models and initialize the database.\n\nWe use `database.init` will Populate relations information and create the tables.\n\n```python\nasync def demo() -> None:\n async def _init() -> None:\n async with db._engine.begin() as conn:\n await db.init()\n await conn.run_sync(db._metadata.drop_all)\n await conn.run_sync(db._metadata.create_all)\n await _init()\n```\n\n#### Insert\n\nNow let's imagine we have another table called `Coffee` that has a foreign key to `Flavor`.\n\n```python\n@database.table(pk=\"id\")\nclass Coffee(BaseModel):\n \"\"\"Drink it in the morning.\"\"\"\n\n id: UUID = Field(default_factory=uuid4)\n sweetener: str | None = Field(max_length=63)\n sweetener_count: int | None = None\n flavor: Flavor | UUID\n```\n\nAfter we create the table, we can insert data into the table, using the `database.insert` method, is away we insert a Model Instance.\n\n```python\n# Create a Flavor called \"Vanilla\"\nvanilla = Flavor(name=\"Vanilla\")\n\n# Insert the Flavor into the database\nawait database[Flavor].insert(vanilla)\n\n# Create a Coffee with the Vanilla Flavor\ncoffee = Coffee(sweetener=\"Sugar\", sweetener_count=1, flavor=vanilla)\n\n# Insert the Coffee into the database\nawait database[Coffee].insert(coffee)\n```\n\n#### Searching Queries\n\nAs we know, in SQL, we can search for data using different methods, ex. `WHERE`, `LIKE`, `IN`, `BETWEEN`, etc.\n\nIn Ormdantic, we can search for data using the `database.find_one` or `database.find_many` methods.\n\n* `Find_one` used to find a Model instance by Primary Key, its could also find with `depth` parameter.\n\n```python\n # Find one\n vanilla = await database[Flavor].find_one(flavor.id)\n print(vanilla.name)\n\n # Find one with depth.\n find_coffee = await database[Coffee].find_one(coffee.id, depth=1)\n print(find_coffee.flavor.name)\n```\n\n* `Find_many` used to find Model instances by some condition ex. `where`, `order_by`, `order`, `limit`, `offset`, `depth`.\n\n```python\n # Find many\n await database[Flavor].find_many()\n\n # Get paginated results.\n await database[Flavor].find_many(\n where={\"name\": \"vanilla\"}, order_by=[\"id\", \"name\"], limit=2, offset=2\n )\n```\n\n#### Update / Upsert Queries\n\n##### Update\n\nThe modification of data that is already in the database is referred to as updating. You can update individual rows, all the rows in a table, or a subset of all rows. Each column can be updated separately; the other columns are not affected.\n\n```python\n # Update a Flavor\n flavor.name = \"caramel\"\n await database[Flavor].update(flavor)\n```\n\n##### Upsert\n\nThe `Upsert` method is similar to the Synchronize method with one exception; the `Upsert` method does not delete any records. The `Upsert` method will result in insert or update operations. If the record exists, it will be updated. If the record does not exist, it will be inserted.\n\n```python\n # Upsert a Flavor\n flavor.name = \"mocha\"\n await database[Flavor].upsert(flavor)\n```\n\n### Delete\n\nThe `DELETE` statement is used to delete existing records in a table.\n\n```python\n # Delete a Flavor\n await database[Flavor].delete(flavor.id)\n```\n\n### Count\n\nTo count the number of rows of a table or in a result set you can use the `count` function.\n\n```python\n # Count\n count = await database[Flavor].count()\n print(count)\n```\n\n* It's support also `Where` and `Depth`\n\n```python\n count_advanced = await database[Coffee].count(\n where={\"sweetener\": 2}, depth=1\n )\n print(count_advanced)\n```\n\n## Generator Feature\n\nWe introduce a new feature called `Generator`, which is a way to generate a Model instance with random data.\n\nSo, Given a Pydantic model type can generate instances of that model with randomly generated values.\n\nusing `ormdantic.generator.Generator` to generate a Model instance.\n\n```python\nfrom enum import auto, Enum\nfrom uuid import UUID\n\nfrom ormdantic.generator import Generator\nfrom pydantic import BaseModel\n\n\nclass Flavor(Enum):\n MOCHA = auto()\n VANILLA = auto()\n\n\nclass Brand(BaseModel):\n brand_name: str\n\n\nclass Coffee(BaseModel):\n id: UUID\n description: str\n cream: bool\n sweetener: int\n flavor: Flavor\n brand: Brand\n\n\nprint(Generator(Coffee))\n```\n\nso the results will be:\n\n```shell\nid=UUID('93b517c2-083b-457d-a0e5-6e1bd2a927e4')\ndescription='ctWOb' cream=True sweetener=234\nflavor=<Flavor.VANILLA: 2> brand=Brand(brand_name='LMrIf')\n```\n\nWe can integrate this with our database while testing our application (Live Tests).\n\n## Development \ud83d\udea7\n\n### Setup environment \ud83d\udce6\n\nYou should create a virtual environment and activate it:\n\n```bash\npython -m venv venv/\n```\n\n```bash\nsource venv/bin/activate\n```\n\nAnd then install the development dependencies:\n\n```bash\n# Install dependencies\npip install -r requirements/all.txt\n```\n\n### Run tests \ud83c\udf1d\n\nYou can run all the tests with:\n\n```bash\nbash scripts/test.sh\n```\n\n### Format the code \ud83c\udf42\n\nExecute the following command to apply `pre-commit` formatting:\n\n```bash\nbash scripts/format.sh\n```\n\nExecute the following command to apply `mypy` type checking:\n\n```bash\nbash scripts/lint.sh\n```\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n",
"bugtrack_url": null,
"license": null,
"summary": "asynchronous ORM that uses pydantic models to represent database tables",
"version": "1.7.0",
"project_urls": {
"Documentation": "https://ormdantic.yezz.me/",
"Funding": "https://github.com/sponsors/yezz123",
"Homepage": "https://github.com/yezz123/ormdantic"
},
"split_keywords": [
"asyncio",
" orm",
" pydantic",
" sqlalchemy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d8eb03d496f563c00f96865acaef3e5523e6ab66aeca77a7f19669cadf094874",
"md5": "70022546ef6f3afb6da2b46cadcfe700",
"sha256": "466d322ae179ebf7dba9a497e06c3f36c2913967d82b51dffa1bb5f181bd5cc7"
},
"downloads": -1,
"filename": "ormdantic-1.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "70022546ef6f3afb6da2b46cadcfe700",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 23449,
"upload_time": "2024-04-19T04:16:17",
"upload_time_iso_8601": "2024-04-19T04:16:17.815942Z",
"url": "https://files.pythonhosted.org/packages/d8/eb/03d496f563c00f96865acaef3e5523e6ab66aeca77a7f19669cadf094874/ormdantic-1.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "321c9b67fe417b6ae18e67ec429f8c9a5a5b7aa9e8ec2f784a1b97bbb03394ee",
"md5": "95a97b0fa43e8b0e4ded09a98240cd87",
"sha256": "09965f5e0fa7f832253a0a27782ed9105d179d8b6b7ae6ea01e1f9dcc5535897"
},
"downloads": -1,
"filename": "ormdantic-1.7.0.tar.gz",
"has_sig": false,
"md5_digest": "95a97b0fa43e8b0e4ded09a98240cd87",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 64502,
"upload_time": "2024-04-19T04:16:19",
"upload_time_iso_8601": "2024-04-19T04:16:19.420252Z",
"url": "https://files.pythonhosted.org/packages/32/1c/9b67fe417b6ae18e67ec429f8c9a5a5b7aa9e8ec2f784a1b97bbb03394ee/ormdantic-1.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-19 04:16:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sponsors",
"github_project": "yezz123",
"github_not_found": true,
"lcname": "ormdantic"
}
