sqlite3_hat 0.1__tar.gz → 0.2__tar.gz

{sqlite3_hat-0.1 → sqlite3_hat-0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlite3_hat
-Version: 0.1
+Version: 0.2
 Summary: Lightweight wrapper with improvements on sqlite3
 Author-email: Thomas Kluyver <takluyver@fastmail.com>
 Requires-Python: >=3.12
@@ -17,13 +17,19 @@ module from the standard library.
 ``sqlite3_hat`` adds (or changes):
 
 - Nested transaction support, using SQLite savepoints
-- Autocommit is on (see why autocommit)
+- Autocommit is on (see the `docs on autocommit
+  <https://sqlite3-hat.readthedocs.io/en/latest/vs-stdlib.html#autocommit>`_ for
+  the rationale)
 - Foreign key enforcement is on
 - Non-standard double-quoted string syntax is disabled by default
 - Convenient way to open a database read-only
 - Parameters can be supplied in t-strings, or as ``*args`` rather than tuples
 - Shortcut ``.queryone()`` method for getting a single row
+- ``Table`` objects wrapping database tables, and a `dict-style
+  interface <https://sqlite3-hat.readthedocs.io/en/latest/mapping.html>`_
+  to access a table by a unique key.
 
 The API is very similar to ``sqlite3``, but it's not a complete drop-in
-replacement.
+replacement. The `porting guide <https://sqlite3-hat.readthedocs.io/en/latest/vs-stdlib.html#porting>`_
+describes a strategy to adopt it in existing code.
 

sqlite3_hat-0.2/README.rst

@@ -0,0 +1,21 @@
+``sqlite3_hat`` is a small, pure Python wrapper to improve the ``sqlite3``
+module from the standard library.
+
+``sqlite3_hat`` adds (or changes):
+
+- Nested transaction support, using SQLite savepoints
+- Autocommit is on (see the `docs on autocommit
+  <https://sqlite3-hat.readthedocs.io/en/latest/vs-stdlib.html#autocommit>`_ for
+  the rationale)
+- Foreign key enforcement is on
+- Non-standard double-quoted string syntax is disabled by default
+- Convenient way to open a database read-only
+- Parameters can be supplied in t-strings, or as ``*args`` rather than tuples
+- Shortcut ``.queryone()`` method for getting a single row
+- ``Table`` objects wrapping database tables, and a `dict-style
+  interface <https://sqlite3-hat.readthedocs.io/en/latest/mapping.html>`_
+  to access a table by a unique key.
+
+The API is very similar to ``sqlite3``, but it's not a complete drop-in
+replacement. The `porting guide <https://sqlite3-hat.readthedocs.io/en/latest/vs-stdlib.html#porting>`_
+describes a strategy to adopt it in existing code.

sqlite3_hat-0.2/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

sqlite3_hat-0.2/docs/api.rst

@@ -0,0 +1,74 @@
+API Reference
+=============
+
+.. currentmodule:: sqlite3_hat
+
+The API is similar to :mod:`sqlite3`.
+
+.. autofunction:: connect
+
+.. autofunction:: open
+
+    Usage::
+
+        with sqlite3_hat.open("foo.db") as conn:
+            conn.execute(...)
+
+.. class:: Connection
+
+    The primary interface to an open SQLite database.
+    Use :func:`connect` or :func:`open` to make a Connection object.
+
+    .. automethod:: execute
+    .. automethod:: executescript
+    .. automethod:: executemany
+    .. automethod:: queryone
+
+    .. automethod:: savepoint
+
+       .. seealso::
+          `Savepoints in SQLite docs <https://sqlite.org/lang_savepoint.html>`_
+
+    .. automethod:: transaction
+
+        .. seealso::
+           `Transactions in SQLite docs <https://sqlite.org/lang_transaction.html>`_
+
+    .. automethod:: commit
+    .. automethod:: rollback
+
+    .. automethod:: table
+
+.. class:: Table
+
+    A wrapper for a database table. Call :meth:`Connection.table` to make a
+    Table object.
+
+   .. attribute:: columns
+
+      A tuple of selected column names. Initially this is all columns except for
+      hidden columns in virtual tables - the same columns you'd get with
+      ``SELECT *``. Use :meth:`select_columns` to get a different selection.
+
+   .. automethod:: select_columns
+   .. automethod:: nrows
+   .. automethod:: read_cursor
+   .. automethod:: insert
+   .. automethod:: insertmany
+   .. automethod:: mapping
+
+Other functions
+---------------
+
+.. autofunction:: quote_name
+
+Exceptions
+----------
+
+:exc:`sqlite3.Error` and its subclasses can all be raised by this module.
+
+.. autoexception:: NoResultsError
+
+.. autoexception:: TableNameError
+
+.. autoexception:: ColumnNameError

sqlite3_hat-0.2/docs/conf.py

@@ -0,0 +1,34 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'sqlite3_hat'
+copyright = '2026, Thomas Kluyver'
+author = 'Thomas Kluyver'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+import os, sys
+sys.path.insert(0, os.path.dirname(os.path.dirname(__file__)))
+
+extensions = [
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']

sqlite3_hat-0.1/README.rst → sqlite3_hat-0.2/docs/index.rst

@@ -1,15 +1,33 @@
+sqlite3_hat
+============
+
 ``sqlite3_hat`` is a small, pure Python wrapper to improve the ``sqlite3``
 module from the standard library.
 
 ``sqlite3_hat`` adds (or changes):
 
 - Nested transaction support, using SQLite savepoints
-- Autocommit is on (see why autocommit)
+- Autocommit is on (see :ref:`autocommit` for rationale)
 - Foreign key enforcement is on
 - Non-standard double-quoted string syntax is disabled by default
 - Convenient way to open a database read-only
 - Parameters can be supplied in t-strings, or as ``*args`` rather than tuples
 - Shortcut ``.queryone()`` method for getting a single row
+- :class:`~.Table` objects wrapping database tables, and a :doc:`dict-style
+  interface <mapping>` to access a table by a unique key.
+
+Install it with::
+
+    pip install sqlite3_hat
 
 The API is very similar to ``sqlite3``, but it's not a complete drop-in
-replacement.
+replacement. See :ref:`porting` for how to adopt it in existing code.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   tutorial.rst
+   mapping.rst
+   vs-stdlib.rst
+   api.rst

sqlite3_hat-0.2/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

sqlite3_hat-0.2/docs/mapping.rst

@@ -0,0 +1,112 @@
+Mapping interface
+=================
+
+A lot of simple data access is based on unique IDs. The mapping interface
+lets you use a database table like a dictionary:
+
+.. testsetup:: mapping
+
+    import sqlite3_hat
+    conn = sqlite3_hat.connect(":memory:")
+
+.. testcode:: mapping
+
+    conn.execute("""CREATE TABLE settings(
+        name TEXT PRIMARY KEY NOT NULL,
+        value,
+        user_set INTEGER DEFAULT 0
+    )""")
+    settings = conn.table("settings").mapping()
+
+    #        name     : (value, user_set)
+    settings["theme"] = ("light", 0)
+    settings.update(view_width=(800, 0), view_height=(600, 0))
+
+    if settings["theme"][0] == "light":
+        ...
+
+.. testcode:: mapping
+    :hide:
+
+    assert settings["theme"] == ("light", 0)
+    assert settings["view_width"][0] == 800
+
+You can use almost all dictionary methods; more precisely, the mapping object
+implements the :class:`~collections.abc.MutableMapping` interface.
+
+By default, the keys are the table's primary key column (or columns), and the
+values are all the other columns. But you can select specific columns:
+
+.. testcode:: mapping
+
+    setting_values = conn.table("settings").mapping(value="value")
+
+    setting_values["time_zone"] = "UTC"
+
+    if setting_values.get("theme", "light") == "dark":
+        ...
+
+.. note::
+
+    Selecting columns for values, as shown here, is mostly simple.
+
+    You can also select different columns for keys, but the selected column(s)
+    should have a UNIQUE constraint (PRIMARY KEY also implies uniqueness).
+
+    You should not use ``None`` in keys, because a column with a UNIQUE
+    constraint can still have multiple NULL values. If possible, use a NOT NULL
+    constraint on key columns to ensure no NULLs creep in.
+
+Transactions
+------------
+
+Mapping objects work with :ref:`database transactions <tutorial-transactions>`.
+If a transaction is open, any changes you make to the mapping are only saved
+when the transaction is committed.
+
+.. testcode:: mapping
+
+    with conn:
+        settings["theme"] = ("high-contrast", 1)
+        settings["font_size"] = ("14pt", 1)
+
+    # Leaving the 'with conn' block commits the changes
+
+Each database method is atomic, and will act on a consistent view of the
+database. For instance, ``settings.update()`` will either make all the given
+updates, or none of them.
+
+.. testcode:: mapping
+
+    # Don't do this:
+    if 'theme' in settings:
+        # between these steps, another process could delete the entry
+        del settings['theme']
+
+    # Do this instead:
+    settings.pop('theme', None)
+
+Iterators
+---------
+
+Iterating over keys, values or items in the mapping is *lazy*, loading the data
+as needed rather than reading it all up front. However, it means keeping a read
+transaction open on the database, which may block writing until it finishes.
+So if the code in the loop might be slow, it's a good idea to read all the
+entries into a list before looping:
+
+.. testsetup:: mapping
+
+    def user_confirm(prompt): return
+    def settings_input_generator(): return []
+
+.. testcode:: mapping
+
+    # list() collects the data in memory & finishes reading
+    for k, v in list(setting_values.items()):
+        user_confirm(f"Setting {k} is set to {v} - OK?")
+
+Writing data with ``mapping.update(slow_iterator)`` can be even worse, because
+this keeps a write transaction open until the iterator finishes, which can block
+both readers and writers. Try to either group changes in memory before calling
+``.update()``, or split it up into smaller changes.

sqlite3_hat-0.2/docs/tutorial.rst

@@ -0,0 +1,278 @@
+Getting started with sqlite3_hat
+=================================
+
+This guide is about writing new code. See :ref:`porting` to adapt existing code
+using ``sqlite3``.
+
+.. _tutorial-connect:
+
+Opening a database
+------------------
+
+Everything you'll do with SQLite starts with opening a database file:
+
+::
+
+    import sqlite3_hat
+    conn = sqlite3_hat.connect("library.sqlite")
+
+The default will create this file if it doesn't exist. If you don't want this,
+pass ``mode="ro"`` (read-only) or ``mode="rw"`` (read-write).
+
+The special filename ``:memory:`` will create a transient in-memory database.
+This is especially useful for writing tests.
+
+.. _tutorial-schema:
+
+Setting up tables and indexes
+-----------------------------
+
+For many database use cases, the next step is to define your *schema*, the
+tables, indexes, etc. that structure your data. Of course, you can skip this
+if you're opening a database created by other code.
+
+.. testsetup:: tutorial
+
+    import sqlite3_hat
+    conn = sqlite3_hat.connect(":memory:")
+
+.. testcode:: tutorial
+
+    conn.executescript("""
+        CREATE TABLE IF NOT EXISTS book(
+            id INTEGER PRIMARY KEY,
+            title TEXT,
+            author TEXT
+        );
+        CREATE TABLE IF NOT EXISTS borrower(
+            id INTEGER PRIMARY KEY,
+            name TEXT,
+            card_num TEXT UNIQUE
+        );
+        CREATE TABLE IF NOT EXISTS loan(
+            book INTEGER REFERENCES book(id) ON DELETE CASCADE,
+            -- SQL comments look like this!
+            -- RESTRICT forbids deleting a borrower with loans
+            borrower INTEGER REFERENCES borrower(id) ON DELETE RESTRICT,
+            due TEXT  -- ISO format: YYYY-MM-DD
+        );
+        CREATE INDEX IF NOT EXISTS loan_by_book ON loan(book);
+        CREATE INDEX IF NOT EXISTS loan_by_borrower ON loan(borrower);
+    """)
+
+Looking up data in a table with many rows is much faster if there's an index
+on the field being used. PRIMARY KEY and UNIQUE columns get indexes
+automatically, and you can choose to create indexes for other columns, as shown
+above.
+
+Designing a good schema for your data is a big topic, which I won't attempt to
+cover here. You may well also need to think about *migrations*, how to modify
+the structure of an existing database as your code evolves.
+
+.. note::
+
+   The examples here use capitals for SQL keywords like ``CREATE``, and
+   lowercase for names like ``book``. This is a common convention, but it's
+   not required.
+
+The SQL commands for creating objects are:
+
+- `CREATE TABLE <https://sqlite.org/lang_createtable.html>`_
+- `CREATE INDEX <https://sqlite.org/lang_createindex.html>`_
+- `CREATE VIRTUAL TABLE <https://sqlite.org/lang_createvtab.html>`_ (used with extensions like full text search)
+- `CREATE VIEW <https://sqlite.org/lang_createview.html>`_ (views are like tables generated from SQL queries)
+- `CREATE TRIGGER <https://sqlite.org/lang_createtrigger.html>`_ (triggers can do things when data is modified)
+
+.. _tutorial-write:
+
+Writing data
+------------
+
+The key SQL statements for writing are `INSERT <https://sqlite.org/lang_insert.html>`_
+and `UPDATE <https://sqlite.org/lang_update.html>`_:
+
+.. testcode:: tutorial
+
+    cur = conn.execute(
+        "INSERT INTO borrower(name, card_num) VALUES (?, ?)",
+        "Thomas Klyuver", "D98765"
+    )
+    borrower_id = cur.lastrowid
+
+    # Fix a typo
+    conn.execute(
+        "UPDATE borrower SET name=? WHERE id=?", "Thomas Kluyver", borrower_id
+    )
+
+The ``cursor.lastrowid`` attribute gives you the *row ID* after a successful
+insert. Because we defined the ``id`` column in the table as
+`INTEGER PRIMARY KEY <https://sqlite.org/lang_createtable.html#rowids_and_the_integer_primary_key>`_,
+the row ID is also the value in this column.
+
+It's often useful to use the ``executemany()`` method when writing to make
+a batch of changes efficiently:
+
+.. testcode:: tutorial
+
+    conn.executemany("INSERT INTO book(title, author) VALUES (?, ?)", [
+        ("Northern Lights", "Philip Pullman"),
+        ("Men at Arms", "Terry Pratchett"),
+    ])
+
+Finally, you can also `DELETE <https://sqlite.org/lang_delete.html>`_ rows::
+
+    conn.execute("DELETE FROM borrowers WHERE id=?", borrower_id)
+
+.. _tutorial-params:
+
+Parameters
+----------
+
+Use placeholders, like the ``?`` shown above, and parameters to combine data with
+the SQL code. There are two styles for this:
+
+.. testcode:: tutorial
+
+    # Parameters by order
+    conn.execute("INSERT INTO book(title, author) VALUES (?, ?)",
+                 "4.50 from Paddington", "Agatha Christie")
+
+    # Parameters by name
+    conn.execute("INSERT INTO book(title, author) VALUES (:title, :author)",
+                 {"title": "Death in the Clouds", "author": "Agatha Christie"})
+
+
+**Don't** be tempted to build a string of SQL including the data. That is how
+you get *SQL injection* vulnerabilities, a serious and sadly common kind of
+security issue. Even if you don't think this could matter in your context, get
+into the habit of using placeholders by default, and learn to see it as a code
+smell if SQL is built with string formatting.
+
+Using placeholders can also be more efficient: as the actual SQL is not
+changing, SQLite can cache and reuse the parsed statement. In a simple test
+storing 1000 numbers, using placeholders was twice as fast as formatting the
+numbers into the SQL.
+
+Template strings
+~~~~~~~~~~~~~~~~
+
+You can also use template strings to put values into SQL safely on Python 3.14
+or above:
+
+.. testcode:: tutorial
+
+    author = "J.R.R. Tolkein"
+    conn.execute(
+        t"INSERT INTO book(title, author) VALUES ({'The Hobbit'}, {author})"
+    )
+
+This uses the same placeholder & parameter mechanism to combine the data with
+the SQL. So it's safe against SQL injection, but can only be used in the same
+places that parameters work; e.g. you can't use it to fill in a table or column
+name.
+
+You can also use template strings with ``conn.executemany()`` with this
+comprehension style:
+
+.. testcode:: tutorial
+
+    lotr_books = [
+        "The Fellowship of the Ring",
+        "The Two Towers",
+        "The Return of the King",
+    ]
+    conn.executemany([
+        t"INSERT INTO book(title, author) VALUES ({title}, {author})"
+        for title in lotr_books
+    ])
+
+Only the parameter parts can vary within an ``executemany()`` call - the SQL
+template must be the same in all entries.
+
+.. _tutorial-transactions:
+
+Transactions
+------------
+
+The modifications above will all take effect as soon as they finish.
+But you can also wrap a group of changes in a transaction. This achieves two
+things:
+
+1. If there's an error during a transaction, it can be rolled back. The changes
+   within the transaction are either all saved, or none of them are (the
+   transaction is *atomic*).
+2. Making multiple changes within a transaction is more efficient than letting
+   SQLite commit each change separately.
+
+For our library example, let's imagine members of another library are allowed to
+borrow books, and we've decided to create a temporary borrower in our database
+to track each outside loan. When the book is returned, the temporary borrower
+should be deleted again.
+
+Transactions can be made using the connection object as a context manager:
+
+.. testcode:: tutorial
+    :hide:
+
+    def is_temp(borrower_id): return True  # To make the example below work
+
+.. testcode:: tutorial
+
+    # Borrow
+    with conn:
+        cur = conn.execute("INSERT INTO borrower(name) VALUES (?)",
+                           "Card #1234 from Othersville library",)
+        conn.execute("INSERT INTO loan(book, borrower) VALUES (?, ?)",
+                     4, cur.lastrowid)
+
+    # Return
+    borrower_id, = conn.queryone(
+        "SELECT borrower FROM loan WHERE book=?", 4
+    )
+    with conn:
+        conn.execute("DELETE FROM loan WHERE book=?", 4)
+        if is_temp(borrower_id):
+            conn.execute(
+                "DELETE FROM borrower WHERE id=?", borrower_id,
+            )
+
+The transaction is committed at the end of the ``with`` block if there's no
+exception, or rolled back if an exception is raised.
+
+Transactions can be nested, and each level of transaction can be committed or
+rolled back. Only when the outermost transaction is committed are any changes
+visible to other connections. See `Savepoints in the SQLite docs
+<https://sqlite.org/lang_savepoint.html>`_ for more about how nested
+transactions work.
+
+
+.. _tutorial-read:
+
+Reading data
+------------
+
+The `SELECT <https://sqlite.org/lang_select.html>`_ statement is the workhorse
+of getting data out of the database:
+
+.. testcode:: tutorial
+
+    rows = conn.execute(
+        "SELECT title FROM book WHERE author=?", "Agatha Christie"
+    ).fetchall()
+    for title, in rows:
+        print(title)
+
+.. testoutput:: tutorial
+
+    4.50 from Paddington
+    Death in the Clouds
+
+The ``queryone`` method is a shortcut for reading a single row, and will raise
+a clear error if no match is returned:
+
+.. testcode:: tutorial
+
+    num_books = conn.queryone("SELECT count(*) FROM book")[0]
+    borrower_id, name = conn.queryone(
+        "SELECT id, name FROM borrower WHERE card_num=?", "D98765"
+    )