Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/seandstewart/yesql
YeSQL is a SQL-first data manipulation library that will replace your ORM.
https://github.com/seandstewart/yesql
database dbapi dbapi2 orm postgresql sql sqlite
Last synced: 2 months ago
JSON representation
YeSQL is a SQL-first data manipulation library that will replace your ORM.
- Host: GitHub
- URL: https://github.com/seandstewart/yesql
- Owner: seandstewart
- License: other
- Created: 2021-07-20T14:42:32.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-07-26T22:02:14.000Z (5 months ago)
- Last Synced: 2024-07-26T23:22:44.103Z (5 months ago)
- Topics: database, dbapi, dbapi2, orm, postgresql, sql, sqlite
- Language: Python
- Homepage:
- Size: 560 KB
- Stars: 16
- Watchers: 5
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# yesql
[](https://pypi.org/project/yesql/)
[](https://pypi.org/project/yesql/)
[](https://pypi.org/project/yesql/)
[](https://github.com/seandstewart/yesql)
[](https://github.com/seandstewart/yesql/actions)
[](https://codecov.io/gh/seandstewart/yesql)
[](https://github.com/ambv/black)
Say _yes_ to _SQL_ with **yesql**.
yesql eliminates boilerplate without the baggage of an expensive or clunky ORM.
Simply write your SQL, point yesql to the directory, and it does all the rest.
## Quickstart
### Installation
```shell
pip install -U --pre yesql
```
or
```shell
poetry add --allow-prereleases yesql
```
yesql currently supports the following database drivers:
- [asyncpg][1]
- [psycopg][2]
You can select your driver as an extra when installing yesql _(recommended)_:
```shell
pip install -U --pre "yesql[psycopg]"
```
or
```shell
poetry add --allow-prereleases yesql -E asyncpg
```
### Basic Usage
```python
from __future__ import annotations
import dataclasses
import datetime
import pathlib
import yesql
QUERIES = pathlib.Path(__file__).resolve().parent / "queries"
@dataclasses.dataclass(slots=True, kw_only=True)
class Post:
id: int | None = None
slug: str | None = None
title: str | None = None
subtitle: str | None = None
tagline: str | None = None
body: str | None = None
tags: set[str] = dataclasses.field(default_factory=set)
publication_date: datetime.date | None = None
created_at: datetime.datetime | None = None
updated_at: datetime.datetime | None = None
class PostsRepository(yesql.SyncQueryRepository[Post]):
"""An asyncio-native service for querying blog posts."""
class metadata(yesql.QueryMetadata):
__querylib__ = QUERIES
__tablename__ = "posts"
__exclude_fields__ = frozenset(("slug",))
posts = PostsRepository()
posts.initialize()
new_post = Post(
title="My Great Blog Post",
subtitle="It's super great. Trust me...",
tagline="You'll be glad you read it.",
tags={"tips", "tricks", "cool stuff"},
)
saved_post = posts.create(instance=new_post)
```
#### Type-stub Generation (Experimental)
yesql ships with simple CLI for generating type-stubs. This allows for more exact
static type-analysis and enables auto-complete for your IDE.
Usage:
```shell
yesql stubgen
```
You can optionally supply any number of paths to directories or python modules. The
command will default to the current working directory on the filesystem.
If you don't have [black][3] installed in your development environment, you should add
the `cli` extra as a development dependency.
## Features
- [x] Support for synchronous IO
- [x] Support for asynchronous IO (asyncio)
- [x] Support for PostgreSQL
- [x] Plays well with MyPy
- [x] Plays well with IDEs
- [x] Encourages best-practices for data-access (Separation of Concerns, Repository
Pattern)
## No ORMs?
1. *ORMs are bad for you.*
They are a leaky abstraction that cannot solve the problem they set out to do - which
is to abstract out the details of working with a database.
2. *ORMs are slow.*
ORMs depend upon a high level of abstraction in order to work across database
clients. They also attempt to bridge the gap of data validation and state
management. By attempting to hide the details of managing state from the end
user, they suffer from large computational costs and predict
3. *ORMs are wasteful.*
As mentioned above, ORMs use a huge amount of resources to auto-magically determine
state for anything and everything currently pulled into your application's memory.
Because this is implicit, this takes a large amount of work to do right. In general,
your application is already aware of "clean" and "dirty" states. Your application
should be in charge of managing it.
4. *ORMs encourage bad data modeling.*
ORMs vastly simplify recursive data modeling (see: N+1 problem) which encourages lazy
solutions to simple problems and can result in extreme service degradation without
reasonable means of mitigation.
## Why yesql?
yesql takes a SQL-first approach to data management:
1. *Focus on your SQL and your database.*
- Reduce developer overhead by having one less middleman between you and your data.
- Easily fine-tune your SQL to take full advantage of the RDBMS you choose.
- No guesswork about what SQL is actually being executed on your database.
2. *Explicit state management.*
- No surprise writes or reads, you control when you read and when you write.
- There is no question whether data is in-memory or in the database.
3. *Plain Ol' Data Objects.*
- Model your data with a mapping, a namedtuple, a dataclass, or just use the native
record objects of your preferred library.
- Loose ser/des based on your model, which can be overridden at any point.
- No implicit state mapping of data from a table to your model. Your query powers
your model.
## v1.0.0 Roadmap
- [x] Query Library Bootstrapping
- [x] Dynamic Query Library
- [ ] Full Documentation Coverage
- [ ] Full Test Coverage
- [ ] Dialect Support
- [x] Async PostgreSQL (via asyncpg & psycopg3)
- [ ] Async SQLite
- [ ] Async MySQL
- [x] Sync PostgreSQL
- [ ] Sync SQLite
- [ ] Sync MySQL
## License
[MIT](https://sean-dstewart.mit-license.org/)
[1]: https://magicstack.github.io/asyncpg/current/
[2]: https://www.psycopg.org/psycopg3/docs/
[3]: https://black.readthedocs.io/en/stable/