Metadata-Version: 2.4
Name: TyDB
Version: 0.1.1
Summary: A simple, type-friendly ORM.
Author-email: Terrance <tydb@terrance.allofti.me>
License-Expression: BSD-3-Clause
Project-URL: homepage, https://tydb.t.allofti.me
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pypika
Requires-Dist: typing_extensions>=4.0.1
Provides-Extra: dev
Requires-Dist: pdoc; extra == "dev"
Requires-Dist: aiomysql; extra == "dev"
Requires-Dist: aiopg; extra == "dev"
Requires-Dist: aiosqlite; extra == "dev"
Requires-Dist: psycopg; extra == "dev"
Requires-Dist: pymysql; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Dynamic: license-file

# TyDB

A simple, type-friendly Python ORM.

## Features

Things one might expect of any ORM:

* Lightweight class-based models and descriptor-based fields
* Built-in fields for common types
* Primary keys
* Foreign keys with attribute accessors and joined queries
* Separate nullable fields

Things one might not:

* Reliable type signatures on the public API
* Support for any [DB-API 2.0](https://peps.python.org/pep-0249/) database driver
* Synchronous and asynchronous operation under a common API

## Database support

Low-level interaction with databases is handled by a [DB-API `Connection`](https://peps.python.org/pep-0249/#connection-objects).  This means you can work with any type of database, as long as a database driver exists that implements a DB-API interface -- Python's built-in SQLite library does so, whilst external modules are available for MySQL, PostgreSQL and others.

Whilst there's no asynchronous DB-API specification, some database drivers implement a DB-API-like interface with the same methods presented as coroutines; these are supported with asynchronous sessions, which will attempt to await results of `Connection` method calls if they return awaitables.

## Local development

To install the library from a code checkout, including development dependencies:

```shell
$ pip install -e '.[dev]'
```

### Docs

These can be built using [pdoc](https://pdoc.dev), assuming you've installed the dev requirements already:

```shell
$ make docs
```

### Unit tests

The included tests can be ran using:

```shell
$ make test
```

By default, this will just run generic tests, and SQLite tests against an in-memory database.

To run against MySQL or PostgreSQL, you'll need the corresponding database drivers installed from the dev dependencies.  Credentials must also be provided to connect to live database servers.  These should be JSON-formatted strings containing `kwargs` for the underlying driver connection methods.  For example, to connect to servers listening locally without authentication:

```shell
$ export TYDB_MYSQL_CONN='{"db": "tydb"}'
$ export TYDB_PGSQL_CONN='{"dbname": "tydb"}'
```

Only synchronous session and driver tests are run by default. To enable asynchronous tests too:

```shell
$ export TYDB_ASYNC=1
```

The dialect-aware tests currently use the following databases and drivers:

* MySQL
  * [`pymysql`](https://pypi.org/project/pymysql/)
  * [`aiomysql`](https://pypi.org/project/aiomysql/)
* PostgreSQL
  * [`psycopg`](https://pypi.org/project/psycopg/)
  * [`aiopg`](https://pypi.org/project/aiopg/)
* SQLite
  * [`sqlite3`](https://docs.python.org/3/library/sqlite3.html) (built-in)
  * [`aiosqlite`](https://pypi.org/project/aiosqlite/)
