README.md

yesql

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

pip install -U --pre yesql

or

poetry add --allow-prereleases yesql

yesql currently supports the following database drivers:

• asyncpg
• psycopg

You can select your driver as an extra when installing yesql (recommended):

pip install -U --pre "yesql[psycopg]"

or

poetry add --allow-prereleases yesql -E asyncpg

Basic Usage

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:

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 installed in your development environment, you should add the cli extra as a development dependency.

Features

• Support for synchronous IO
• Support for asynchronous IO (asyncio)
• Support for PostgreSQL
• Plays well with MyPy
• Plays well with IDEs
• 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

• Query Library Bootstrapping
• Dynamic Query Library
• Full Documentation Coverage
• Full Test Coverage
• Dialect Support
  • Async PostgreSQL (via asyncpg & psycopg3)
  • Async SQLite
  • Async MySQL
  • Sync PostgreSQL
  • Sync SQLite
  • Sync MySQL

License

MIT