Skip to content

Commit

Permalink
deploy: fda2a36
Browse files Browse the repository at this point in the history
  • Loading branch information
github-actions[bot] committed Dec 23, 2024
0 parents commit 622d13d
Show file tree
Hide file tree
Showing 23 changed files with 6,126 additions and 0 deletions.
Empty file added .nojekyll
Empty file.
860 changes: 860 additions & 0 deletions index.html

Large diffs are not rendered by default.

277 changes: 277 additions & 0 deletions index.html.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,277 @@
# apswutils


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

<div>

> **Where to find the complete documentation for this library**
>
> If you want to learn about everything this project can do, we
> recommend reading the Python library section of the sqlite-utils
> project
> [here](https://sqlite-utils.datasette.io/en/stable/python-api.html).
>
> This project wouldn’t exist without Simon Willison and his excellent
> [sqlite-utils](https://github.com/simonw/sqlite-utils) project. Most
> of this project is his code, with some minor changes made to it.
</div>

## Install

pip install apswutils

## Use

First, import the apswutils library. Through the use of the **all**
attribute in our Python modules by using `import *` we only bring in the
`Database`, `Queryable`, `Table`, `View` classes. There’s no risk of
namespace pollution.

``` python
from apswutils.db import *
```

Then we create a SQLite database. For the sake of convienance we’re
doing it in-memory with the `:memory:` special string. If you wanted
something more persistent, name it something not surrounded by colons,
`data.db` is a common file name.

``` python
db = Database(":memory:")
```

Let’s drop (aka ‘delete’) any tables that might exist. These docs also
serve as a test harness, and we want to make certain we are starting
with a clean slate. This also serves as a handy sneak preview of some of
the features of this library.

``` python
for t in db.tables: t.drop()
```

User tables are a handy way to create a useful example with some
real-world meaning. To do this, we first instantiate the `users` table
object:

``` python
users = Table(db, 'Users')
users
```

<Table Users (does not exist yet)>

The table doesn’t exist yet, so let’s add some columns via the
`Table.create` method:

``` python
users.create(columns=dict(id=int, name=str, age=int))
users
```

<Table Users (id, name, age)>

What if we need to change the table structure?

For example User tables often include things like password field. Let’s
add that now by calling `create` again, but this time with
`transform=True`. We should now see that the `users` table now has the
`pwd:str` field added.

``` python
users.create(columns=dict(id=int, name=str, age=int, pwd=str), transform=True, pk='id')
users
```

<Table Users (id, name, age, pwd)>

``` python
print(db.schema)
```

CREATE TABLE "Users" (
[id] INTEGER PRIMARY KEY,
[name] TEXT,
[age] INTEGER,
[pwd] TEXT
);

## Queries

Let’s add some users to query:

``` python
users.insert(dict(name='Raven', age=8, pwd='s3cret'))
users.insert(dict(name='Magpie', age=5, pwd='supersecret'))
users.insert(dict(name='Crow', age=12, pwd='verysecret'))
users.insert(dict(name='Pigeon', age=3, pwd='keptsecret'))
users.insert(dict(name='Eagle', age=7, pwd='s3cr3t'))
```

<Table Users (id, name, age, pwd)>

A simple unfiltered select can be executed using `rows` property on the
table object.

``` python
users.rows
```

<generator object Queryable.rows_where>

Let’s iterate over that generator to see the results:

``` python
[o for o in users.rows]
```

[{'id': 1, 'name': 'Raven', 'age': 8, 'pwd': 's3cret'},
{'id': 2, 'name': 'Magpie', 'age': 5, 'pwd': 'supersecret'},
{'id': 3, 'name': 'Crow', 'age': 12, 'pwd': 'verysecret'},
{'id': 4, 'name': 'Pigeon', 'age': 3, 'pwd': 'keptsecret'},
{'id': 5, 'name': 'Eagle', 'age': 7, 'pwd': 's3cr3t'}]

Filtering can be done via the `rows_where` function:

``` python
[o for o in users.rows_where('age > 3')]
```

[{'id': 1, 'name': 'Raven', 'age': 8, 'pwd': 's3cret'},
{'id': 2, 'name': 'Magpie', 'age': 5, 'pwd': 'supersecret'},
{'id': 3, 'name': 'Crow', 'age': 12, 'pwd': 'verysecret'},
{'id': 5, 'name': 'Eagle', 'age': 7, 'pwd': 's3cr3t'}]

We can also `limit` the results:

``` python
[o for o in users.rows_where('age > 3', limit=2)]
```

[{'id': 1, 'name': 'Raven', 'age': 8, 'pwd': 's3cret'},
{'id': 2, 'name': 'Magpie', 'age': 5, 'pwd': 'supersecret'}]

The `offset` keyword can be combined with the `limit` keyword.

``` python
[o for o in users.rows_where('age > 3', limit=2, offset=1)]
```

[{'id': 2, 'name': 'Magpie', 'age': 5, 'pwd': 'supersecret'},
{'id': 3, 'name': 'Crow', 'age': 12, 'pwd': 'verysecret'}]

The `offset` must be used with `limit` or raise a `ValueError`:

``` python
try:
[o for o in users.rows_where(offset=1)]
except ValueError as e:
print(e)
```

Cannot use offset without limit

## Transactions

If you have any SQL calls outside an explicit transaction, they are
committed instantly.

To group 2 or more queries together into 1 transaction, wrap them in a
BEGIN and COMMIT, executing ROLLBACK if an exception is caught:

``` python
users.get(1)
```

{'id': 1, 'name': 'Raven', 'age': 8, 'pwd': 's3cret'}

``` python
db.begin()
try:
users.delete([1])
db.execute('FNOOORD')
db.commit()
except Exception as e:
print(e)
db.rollback()
```

near "FNOOORD": syntax error

Because the transaction was rolled back, the user was not deleted:

``` python
users.get(1)
```

{'id': 1, 'name': 'Raven', 'age': 8, 'pwd': 's3cret'}

Let’s do it again, but without the DB error, to check the transaction is
successful:

``` python
db.begin()
try:
users.delete([1])
db.commit()
except Exception as e: db.rollback()
```

``` python
try:
users.get(1)
print("Delete failed!")
except: print("Delete succeeded!")
```

Delete succeeded!

## Differences from sqlite-utils and sqlite-minutils

- WAL is the default
- Setting `Database(recursive_triggers=False)` works as expected
- Primary keys must be set on a table for it to be a target of a foreign
key
- Errors have been changed minimally, future PRs will change them
incrementally

## Differences in error handling

<table>
<colgroup>
<col style="width: 33%" />
<col style="width: 33%" />
<col style="width: 33%" />
</colgroup>
<thead>
<tr>
<th>Old/sqlite3/dbapi</th>
<th>New/APSW</th>
<th>Reason</th>
</tr>
</thead>
<tbody>
<tr>
<td>IntegrityError</td>
<td>apsw.ConstraintError</td>
<td>Caused due to SQL transformation blocked on database
constraints</td>
</tr>
<tr>
<td>sqlite3.dbapi2.OperationalError</td>
<td>apsw.Error</td>
<td>General error, OperationalError is now proxied to apsw.Error</td>
</tr>
<tr>
<td>sqlite3.dbapi2.OperationalError</td>
<td>apsw.SQLError</td>
<td>When an error is due to flawed SQL statements</td>
</tr>
<tr>
<td>sqlite3.ProgrammingError</td>
<td>apsw.ConnectionClosedError</td>
<td>Caused by an improperly closed database file</td>
</tr>
</tbody>
</table>
1 change: 1 addition & 0 deletions robots.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Sitemap: https://AnswerDotAI.github.io/apswutils/sitemap.xml
72 changes: 72 additions & 0 deletions search.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
[
{
"objectID": "index.html",
"href": "index.html",
"title": "apswutils",
"section": "",
"text": "Where to find the complete documentation for this library\n\n\n\nIf you want to learn about everything this project can do, we recommend reading the Python library section of the sqlite-utils project here.\nThis project wouldn’t exist without Simon Willison and his excellent sqlite-utils project. Most of this project is his code, with some minor changes made to it.",
"crumbs": [
"apswutils"
]
},
{
"objectID": "index.html#install",
"href": "index.html#install",
"title": "apswutils",
"section": "Install",
"text": "Install\npip install apswutils",
"crumbs": [
"apswutils"
]
},
{
"objectID": "index.html#use",
"href": "index.html#use",
"title": "apswutils",
"section": "Use",
"text": "Use\nFirst, import the apswutils library. Through the use of the all attribute in our Python modules by using import * we only bring in the Database, Queryable, Table, View classes. There’s no risk of namespace pollution.\n\nfrom apswutils.db import *\n\nThen we create a SQLite database. For the sake of convienance we’re doing it in-memory with the :memory: special string. If you wanted something more persistent, name it something not surrounded by colons, data.db is a common file name.\n\ndb = Database(\":memory:\")\n\nLet’s drop (aka ‘delete’) any tables that might exist. These docs also serve as a test harness, and we want to make certain we are starting with a clean slate. This also serves as a handy sneak preview of some of the features of this library.\n\nfor t in db.tables: t.drop()\n\nUser tables are a handy way to create a useful example with some real-world meaning. To do this, we first instantiate the users table object:\n\nusers = Table(db, 'Users')\nusers\n\n&lt;Table Users (does not exist yet)&gt;\n\n\nThe table doesn’t exist yet, so let’s add some columns via the Table.create method:\n\nusers.create(columns=dict(id=int, name=str, age=int))\nusers\n\n&lt;Table Users (id, name, age)&gt;\n\n\nWhat if we need to change the table structure?\nFor example User tables often include things like password field. Let’s add that now by calling create again, but this time with transform=True. We should now see that the users table now has the pwd:str field added.\n\nusers.create(columns=dict(id=int, name=str, age=int, pwd=str), transform=True, pk='id')\nusers\n\n&lt;Table Users (id, name, age, pwd)&gt;\n\n\n\nprint(db.schema)\n\nCREATE TABLE \"Users\" (\n [id] INTEGER PRIMARY KEY,\n [name] TEXT,\n [age] INTEGER,\n [pwd] TEXT\n);",
"crumbs": [
"apswutils"
]
},
{
"objectID": "index.html#queries",
"href": "index.html#queries",
"title": "apswutils",
"section": "Queries",
"text": "Queries\nLet’s add some users to query:\n\nusers.insert(dict(name='Raven', age=8, pwd='s3cret'))\nusers.insert(dict(name='Magpie', age=5, pwd='supersecret'))\nusers.insert(dict(name='Crow', age=12, pwd='verysecret'))\nusers.insert(dict(name='Pigeon', age=3, pwd='keptsecret'))\nusers.insert(dict(name='Eagle', age=7, pwd='s3cr3t'))\n\n&lt;Table Users (id, name, age, pwd)&gt;\n\n\nA simple unfiltered select can be executed using rows property on the table object.\n\nusers.rows\n\n&lt;generator object Queryable.rows_where&gt;\n\n\nLet’s iterate over that generator to see the results:\n\n[o for o in users.rows]\n\n[{'id': 1, 'name': 'Raven', 'age': 8, 'pwd': 's3cret'},\n {'id': 2, 'name': 'Magpie', 'age': 5, 'pwd': 'supersecret'},\n {'id': 3, 'name': 'Crow', 'age': 12, 'pwd': 'verysecret'},\n {'id': 4, 'name': 'Pigeon', 'age': 3, 'pwd': 'keptsecret'},\n {'id': 5, 'name': 'Eagle', 'age': 7, 'pwd': 's3cr3t'}]\n\n\nFiltering can be done via the rows_where function:\n\n[o for o in users.rows_where('age &gt; 3')]\n\n[{'id': 1, 'name': 'Raven', 'age': 8, 'pwd': 's3cret'},\n {'id': 2, 'name': 'Magpie', 'age': 5, 'pwd': 'supersecret'},\n {'id': 3, 'name': 'Crow', 'age': 12, 'pwd': 'verysecret'},\n {'id': 5, 'name': 'Eagle', 'age': 7, 'pwd': 's3cr3t'}]\n\n\nWe can also limit the results:\n\n[o for o in users.rows_where('age &gt; 3', limit=2)]\n\n[{'id': 1, 'name': 'Raven', 'age': 8, 'pwd': 's3cret'},\n {'id': 2, 'name': 'Magpie', 'age': 5, 'pwd': 'supersecret'}]\n\n\nThe offset keyword can be combined with the limit keyword.\n\n[o for o in users.rows_where('age &gt; 3', limit=2, offset=1)]\n\n[{'id': 2, 'name': 'Magpie', 'age': 5, 'pwd': 'supersecret'},\n {'id': 3, 'name': 'Crow', 'age': 12, 'pwd': 'verysecret'}]\n\n\nThe offset must be used with limit or raise a ValueError:\n\ntry:\n [o for o in users.rows_where(offset=1)]\nexcept ValueError as e:\n print(e)\n\nCannot use offset without limit",
"crumbs": [
"apswutils"
]
},
{
"objectID": "index.html#transactions",
"href": "index.html#transactions",
"title": "apswutils",
"section": "Transactions",
"text": "Transactions\nIf you have any SQL calls outside an explicit transaction, they are committed instantly.\nTo group 2 or more queries together into 1 transaction, wrap them in a BEGIN and COMMIT, executing ROLLBACK if an exception is caught:\n\nusers.get(1)\n\n{'id': 1, 'name': 'Raven', 'age': 8, 'pwd': 's3cret'}\n\n\n\ndb.begin()\ntry:\n users.delete([1])\n db.execute('FNOOORD')\n db.commit()\nexcept Exception as e:\n print(e)\n db.rollback()\n\nnear \"FNOOORD\": syntax error\n\n\nBecause the transaction was rolled back, the user was not deleted:\n\nusers.get(1)\n\n{'id': 1, 'name': 'Raven', 'age': 8, 'pwd': 's3cret'}\n\n\nLet’s do it again, but without the DB error, to check the transaction is successful:\n\ndb.begin()\ntry:\n users.delete([1])\n db.commit()\nexcept Exception as e: db.rollback()\n\n\ntry:\n users.get(1)\n print(\"Delete failed!\")\nexcept: print(\"Delete succeeded!\")\n\nDelete succeeded!",
"crumbs": [
"apswutils"
]
},
{
"objectID": "index.html#differences-from-sqlite-utils-and-sqlite-minutils",
"href": "index.html#differences-from-sqlite-utils-and-sqlite-minutils",
"title": "apswutils",
"section": "Differences from sqlite-utils and sqlite-minutils",
"text": "Differences from sqlite-utils and sqlite-minutils\n\nWAL is the default\nSetting Database(recursive_triggers=False) works as expected\nPrimary keys must be set on a table for it to be a target of a foreign key\nErrors have been changed minimally, future PRs will change them incrementally",
"crumbs": [
"apswutils"
]
},
{
"objectID": "index.html#differences-in-error-handling",
"href": "index.html#differences-in-error-handling",
"title": "apswutils",
"section": "Differences in error handling",
"text": "Differences in error handling\n\n\n\n\n\n\n\n\nOld/sqlite3/dbapi\nNew/APSW\nReason\n\n\n\n\nIntegrityError\napsw.ConstraintError\nCaused due to SQL transformation blocked on database constraints\n\n\nsqlite3.dbapi2.OperationalError\napsw.Error\nGeneral error, OperationalError is now proxied to apsw.Error\n\n\nsqlite3.dbapi2.OperationalError\napsw.SQLError\nWhen an error is due to flawed SQL statements\n\n\nsqlite3.ProgrammingError\napsw.ConnectionClosedError\nCaused by an improperly closed database file",
"crumbs": [
"apswutils"
]
}
]

Large diffs are not rendered by default.

Loading

0 comments on commit 622d13d

Please sign in to comment.