Apsw

========

This is the last version that supports Python 3.6 and Python 3.7 (both
end of life). The policy as stated in the :doc:`about <about>` page
is that there will be one more APSW release after a Python version
goes end of life supporting that Python version. (:issue:`471`)

Added :doc:`best practice <bestpractice>` module (:issue:`460`)

:meth:`apsw.ext.log_sqlite` outputs SQLite warnings at warning level.
(:issue:`472`)

`sqlite3_stmt_explain <https://sqlite.org/c3ref/stmt_explain.html>`__
is wrapped available as a `explain` keyword parameter on
execute/executemany methods. (:issue:`474`)

Added documentation and :class:`helper class <VFSFcntlPragma>` for
implementing custom `pragmas <https://sqlite.org/pragma.html>`__ in
your own :ref:`VFS` (:issue:`464`)

Reduced overhead of the Column method when using
:meth:`apsw.ext.make_virtual_module` (:issue:`465`)

========

Work with SQLite compiled with `SQLITE_OMIT_DEPRECATED
<https://www.sqlite.org/compile.html#omit_deprecated>`__.
:meth:`Connection.set_profile` was changed from using the deprecated
`sqlite3_profile <https://sqlite.org/c3ref/profile.html>`__ to
`sqlite3_trace_v2 <https://sqlite.org/c3ref/trace_v2.html>`__ giving
the same results. When including the amalgamation,
SQLITE_OMIT_DEPRECATED is defined. (:issue:`443`)

:doc:`shell` updates adding :ref:`various commands <shell-commands>`
to match the SQLite shell, as well as code and documentation
improvements. (:issue:`397`)

Added :meth:`Connection.read` and :func:`apsw.ext.dbinfo` to provide
information from the database and journal/wal files. The shell
command :ref:`.dbinfo <shell-cmd-dbinfo>` displays it.

Added :meth:`apsw.vfs_details`. The shell command
:ref:`.vfslist <shell-cmd-vfslist>` displays it.

Implemented `VFS method xCurrentTimeInt64
<https://sqlite.org/c3ref/vfs.html>`__. The default SQLite VFS no
longer provide ``xCurrentTime`` (floating point version) if
``SQLITE_OMIT_DEPRECATED`` is defined, so this is needed for
inheritance to work. (:issue:`451`)

**Backwards incompatible change**: *VFS* If you override
``xCurrentTime``, then you will need to override ``xCurrentTimeInt64``
in the same way, or ``exclude`` ``xCurrentTimeInt64`` in :class:`VFS`,
or use ``iVersion`` of ``1``.

:ref:`speedtest` now shows summary statistics, and improved help text.
(:issue:`444`)

========

`SQLITE_ENABLE_COLUMN_METADATA
<https://www.sqlite.org/compile.html#enable_column_metadata>`__ is
enabled when installing APSW from `PyPI <https://pypi.org/project/apsw/>`__
(binary or source). (:issue:`435`)

:ref:`Type stubs <type_stubs>` and typing information in the
documentation use newer Python conventions such as `|` instead of
`Union` and `list` instead of `typing.List`, being more concise and
readable. (A recent Python is required to use them, but they have no
effect at runtime.) (:issue:`438`)

Shell: Errors when SQLite are preparing a statement now show the
relevant extract of the query, and where the error was detected.

Shell: Output modes table (ASCII line drawing, lots of sanitization),
box (Unicode line drawing) and qbox (box with quoted values) available.
Python 3.7+ (:issue:`420`)

Shell: if started interactively then box is the default mode (list remains
the default in non-interactive)

Added :meth:`Connection.pragma` to execute pragmas
and get results. (:issue:`432`)

Added :attr:`Cursor.get` returning query results with the
least amount of structure. (:issue:`389`)

Fixed execution tracers should return comment text for comment
only queries, and add :attr:`Cursor.has_vdbe`. (:issue:`433`)

Ensure that all applicable options are implemented for
:func:`apsw.config`, :meth:`Connection.config` and similar.
(:issue:`431`)

Added :func:`apsw.sleep` (:issue:`419`)

Strings for :meth:`apsw.VFS.xNextSystemCall` are :c:func:`interned
<PyUnicode_InternInPlace>` avoiding memory leaks. (:issue:`430`)

Detect unbound recursion not handled by CPython, and handle better.
(:issue:`425`)

========

Fixed :issue:`412` in :meth:`apsw.ext.make_virtual_module`.

Added :meth:`apsw.connections` to get all connections. (:issue:`416`)

:func:`sys.unraisablehook` is called correctly (:issue:`410`)

Be stricter where :class:`bool` values are expected (eg
:meth:`VTTable.BestIndex`), only accepting :class:`int` and
:class:`bool`. Previously you could for example supply strings and
lists, which were almost certainly unintended errors.

========

**Backwards incompatible change**: Bindings using a dictionary with a
missing key now result in a :exc:`KeyError` exception. You can use
:meth:`allow_missing_dict_bindings` to restore the old behaviour.
(:issue:`392`)

Virtual table updates:

* :meth:`VTTable.BestIndexObject` is now available which provides
:class:`IndexInfo` exposing full control (:issue:`332`, :issue:`329`,
:issue:`278`, :issue:`188`)

* :meth:`IndexInfo.set_aConstraintUsage_in` can have *in* values
passed all at once to :meth:`VTCursor.Filter`

* Exceptions in :meth:`VTTable.FindFunction` are now reported as
an :ref:`unraisable exception <unraisable>` because it isn't
possible to tell SQLite about the error.

* :meth:`VTTable.FindFunction` can now return (int, callable)
to allow for virtual table specific function overloads. (:issue:`269`)

* Added :meth:`Connection.vtab_config` and
:meth:`Connection.vtab_on_conflict` (:issue:`189`, :issue:`190`)

* :meth:`Connection.create_module` lets you have `eponymous
<https://sqlite.org/vtab.html#eponymous_virtual_tables>`__,
`eponymous_only
<https://sqlite.org/vtab.html#eponymous_only_virtual_tables>`__, and
read_only modules. (:issue:`196`)

* Virtual table updates can avoid having to provide all column
values when only a subset are changing. See :attr:`apsw.no_change`,
:meth:`Connection.create_module` *use_no_change* parameter,
:meth:`VTCursor.ColumnNoChange` and :meth:`VTTable.UpdateChangeRow`
(:issue:`402`)

* All `virtual table methods <https://www.sqlite.org/c3ref/module.html>`__
are supported - added *iVersion* 2 and 3. You can specify the
*iVersion* in :meth:`Connection.create_module` (:issue:`128`)

* :meth:`apsw.ext.make_virtual_module` makes it very easy to turn
a Python function into a virtual table module.

* :meth:`apsw.ext.generate_series` and :meth:`apsw.ext.generate_series_sqlite`
added. (:issue:`380`)

:meth:`apsw.format_sql_value` now outputs floating point NaN, positive
and negative infinity, and signed zero exactly as SQLite does (:issue:`398`)

Added :meth:`apsw.ext.format_query_table` for handy table output
with auto column sizes, colour, word wrap etc.

Added :meth:`Connection.is_interrupted`.

========

Implemented `window functions
<https://www.sqlite.org/windowfunctions.html#udfwinfunc>`__
(:issue:`292`)

`Function flags <https://www.sqlite.org/c3ref/c_deterministic.html>`__
can be specified to :meth:`Connection.create_scalar_function` and
:meth:`Connection.create_aggregate_function`. Added
:attr:`apsw.mapping_function_flags`. (:issue:`384`)

Added :meth:`Connection.trace_v2` with :attr:`apsw.mapping_trace_codes`
and :attr:`apsw.mapping_statement_status` (:issue:`383`)

Ensure all SQLite APIs are wrapped. :attr:`Connection.system_errno`,
:meth:`apsw.strlike`, :meth:`apsw.strglob`, :meth:`apsw.stricmp`,
:meth:`apsw.strnicmp`, :attr:`Connection.filename_wal`,
:attr:`Connection.filename_journal`, :meth:`Connection.table_exists`,
:meth:`Connection.column_metadata`, :attr:`Error.error_offset`,
:meth:`Connection.cache_flush`, :meth:`Connection.release_memory`,
:meth:`apsw.hard_heap_limit`. :meth:`Connection.drop_modules`
(:issue:`382`)

When an :ref:`unraisable exception <unraisable>` happens, `sqlite3_log
<https://www.sqlite.org/c3ref/log.html>`__ is now called so you will
have context within SQLite's actions. :func:`sys.unraisablehook` is
now called first, and if it doesn't exist then :func:`sys.excepthook`
as before. (:issue:`385`)

When the wrong type is given for a function argument, the error
message now includes the parameter name and function signature.
(:issue:`358`)

Let SQLite do size checking instead of APSW for strings and blobs.
(:issue:`387`)

Added :meth:`apsw.ext.log_sqlite` which installs a handler that
forwards SQLite messages to the :mod:`logging module <logging>`.

Added :meth:`set_default_vfs` and :meth:`unregister_vfs` taking vfs
names. The test suite also unregisters `ZipVFS
<https://www.sqlite.org/zipvfs/doc/trunk/www/index.wiki>`__
(:issue:`394`)