Sqlite-utils

- New experimental `sqlite-utils tui` interface for interactively building command-line invocations, powered by [Trogon](https://github.com/Textualize/trogon). This requires an optional dependency, installed using `sqlite-utils install trogon`. There is a screenshot [in the documentation](https://sqlite-utils.datasette.io/en/stable/cli.html#cli-tui). ([545](https://github.com/simonw/sqlite-utils/issues/545))
- `sqlite-utils analyze-tables` command ([documentation](https://sqlite-utils.datasette.io/en/stable/cli.html#cli-analyze-tables)) now has a `--common-limit 20` option for changing the number of common/least-common values shown for each column. ([544](https://github.com/simonw/sqlite-utils/issues/544))
- `sqlite-utils analyze-tables --no-most` and `--no-least` options for disabling calculation of most-common and least-common values.
- If a column contains only `null` values, `analyze-tables` will no longer attempt to calculate the most common and least common values for that column. ([547](https://github.com/simonw/sqlite-utils/issues/547))
- Calling `sqlite-utils analyze-tables` with non-existent columns in the `-c/--column` option now results in an error message. ([548](https://github.com/simonw/sqlite-utils/issues/548))
- The `table.analyze_column()` method ([documented here](https://sqlite-utils.datasette.io/en/stable/python-api.html#python-api-analyze-column)) now accepts `most_common=False` and `least_common=False` options for disabling calculation of those values.

- Dropped support for Python 3.6. Tests now ensure compatibility with Python 3.11. ([517](https://github.com/simonw/sqlite-utils/issues/517))
- Automatically locates the SpatiaLite extension on Apple Silicon. Thanks, Chris Amico. ([536](https://github.com/simonw/sqlite-utils/pull/536))
- New `--raw-lines` option for the `sqlite-utils query` and `sqlite-utils memory` commands, which outputs just the raw value of the first column of evy row. ([539](https://github.com/simonw/sqlite-utils/issues/539))
- Fixed a bug where `table.upsert_all()` failed if the `not_null=` option was passed. ([538](https://github.com/simonw/sqlite-utils/issues/538))
- Fixed a `ResourceWarning` when using `sqlite-utils insert`. ([534](https://github.com/simonw/sqlite-utils/issues/534))
- Now shows a more detailed error message when `sqlite-utils insert` is called with invalid JSON. ([532](https://github.com/simonw/sqlite-utils/ises/532))
- `table.convert(..., skip_false=False)` and `sqlite-utils convert --no-skip-false` options, for avoiding a misfeature where the [convert()](http://127.0.0.1:8000/python-api.html#python-api-convert) mechanism skips rows in the database with a falsey value for the specified column. Fixing this by default would be a backwards-incompatible change and is under consideration for a 4.0 release in the future. ([527](https://github.com/simonw/sqlite-utils/issues/527))
- Tables can now be created with self-referential foreign keys. Thanks, Scott Perry. ([537](https://github.com/simonw/sqlite-utils/pull/537))
- `sqlite-utils transform` no longer breaks if a table defines default values for columns. Thanks, Kenny Song. ([509](https://github.com/simonw/sqlite-utils/issues/509))
- Fixed a bug where repeated calls to `table.transform()` did not work correctly. Thanks, Martin Carpenter. ([525](https://github.com/simonw/sqlite-utils/issues/525))
- Improved error message if `rows_from_file()` is passed a non-binary-mode file-like object. ([520](https://github.com/simonw/sqlite-utils/issues/520))

- Now tested against Python 3.11. ([502](https://github.com/simonw/sqlite-utils/issues/502))
- New `table.search_sql(include_rank=True)` option, which adds a `rank` column to the generated SQL. Thanks, Jacob Chapman. ([480](https://github.com/simonw/sqlite-utils/pull/480))
- Progress bars now display for newline-delimited JSON files using the `--nl` option. Thanks, Mischa Untaga. ([485](https://github.com/simonw/sqlite-utils/issues/485))
- New `db.close()` method. ([504](https://github.com/simonw/sqlite-utils/issues/504))
- Conversion functions passed to [table.convert(...)](https://sqlite-utils.datasette.io/en/stable/python-api.html#python-api-convert) can now return lists or dictionaries, which will be inserted into the database as JSON strings. ([495](https://github.com/simonw/sqlite-utils/issues/495))
- `sqlite-utils install` and `sqlite-utils uninstall` commands for installing packages into the same virtual environment as `sqlite-utils`, [described here](https://sqlite-utils.datasette.io/en/stable/cli.html#cli-install). ([483](https://github.com/simonw/sqlite-utils/issues/483))
- New [sqlite_utils.utils.flatten()](https://sqlite-utils.datasette.io/en/stable/reference.html#reference-utils-flatten) utility function. ([500](https://github.com/simonw/sqlite-utils/issues/500))
- Documentation on [using Just](https://sqlite-utils.datasette.io/en/stable/contributing.html#contributing-just) to run tests, linters and build documentation.
- Documentation now covers the [Release process](https://sqlite-utils.datasette.io/en/stable/contributing.html#release-process) for this package.

- The `sqlite-utils query`, `memory` and `bulk` commands now all accept a new `--functions` option. This can be passed a string of Python code, and any callable objects defined in that code will be made available to SQL queries as custom SQL functions. See [Defining custom SQL functions](https://sqlite-utils.datasette.io/en/stable/cli.html#cli-query-functions) for details. ([471](https://github.com/simonw/sqlite-utils/issues/471))
- `db[table].create(...)` method now accepts a new `transform=True` parameter. If the table already exists it will be transform to match the schema configuration options passed to the function. This may result in columns being added or dropped, column types being changed, column order being updated or not null and default values for columns being set. ([467](https://github.com/simonw/sqlite-utils/issues/467))
- Related to the above, the `sqlite-utils create-table` command now accepts a `--transform` option.
- New introspection property: `table.default_values` returns a dictionary mapping each column name with a default value to the configured default value. ([475](https://github.com/simonw/sqlite-utils/issues/475))
- The `--load-extension` option can now be provided a path to a compiled SQLite extension module accompanied by the name of an entrypoint, separated by a colon - for example `--load-extension ./lines0:sqlite3_lines0_noread_init`. This feature is modelled on code first [contributed to Datasette](https://github.com/simonw/datasette/pull/1789) by Alex Garcia. ([#470](https://github.com/simonw/sqlite-utils/issues/470))
- Functions registered using the [db.register_function()](https://sqlite-utils.datasette.io/en/stable/python-api.html#python-api-register-function) method can now have a custom name specified using the new `db.register_function(fn, name=...)` parameter. ([458](https://github.com/simonw/sqlite-utils/issues/458))
- [sqlite-utils rows](https://sqlite-utils.datasette.io/en/stable/cli.html#cli-rows) has a new `--order` option for specifying the sort order for the returned rows. ([469](https://github.com/simonw/sqlite-utils/issues/469))
- All of the CLI options that accept Python code blocks can now all be used to define functions that can access modules imported in that same block of code without needing to use the `global` keyword. ([472](https://github.com/simonw/sqlite-utils/issues/472))
- Fixed bug where `table.extract()` would not behave correctly for columns containing null values. Thanks, Forest Gregg. ([423](https://github.com/simonw/sqlite-utils/issues/423))
- New tutorial: [Cleaning data with sqlite-utils and Datasette](https://datasette.io/tutorials/clean-data) shows how to use `sqlite-utils` to import and clean an example CSV file.
- Datasette and `sqlite-utils` now have a Discord community. [Join the Discord here](https://discord.gg/Ass7bCAMDw).

- New [table.duplicate(new_name)](https://sqlite-utils.datasette.io/en/stable/python-api.html#python-api-duplicate) method for creating a copy of a table with a matching schema and row contents. Thanks, [David](https://github.com/davidleejy). ([#449](https://github.com/simonw/sqlite-utils/issues/449))
- New `sqlite-utils duplicate data.db table_name new_name` CLI command for [Duplicating tables](https://sqlite-utils.datasette.io/en/stable/cli.html#cli-duplicate-table). ([454](https://github.com/simonw/sqlite-utils/issues/454))
- `sqlite_utils.utils.rows_from_file()` is now a [documented API](https://sqlite-utils.datasette.io/en/stable/reference.html#reference-utils-rows-from-file). It can be used to read a sequence of dictionaries from a file-like object containing CSV, TSV, JSON or newline-delimited JSON. It can be passed an explicit format or can attempt to detect the format automatically. ([443](https://github.com/simonw/sqlite-utils/issues/443))
- `sqlite_utils.utils.TypeTracker` is now a documented API for detecting the likely column types for a sequence of string rows, see [Detecting column types using TypeTracker](https://sqlite-utils.datasette.io/en/stable/python-api.html#python-api-typetracker). ([445](https://github.com/simonw/sqlite-utils/issues/445))
- `sqlite_utils.utils.chunks()` is now a documented API for [splitting an iterator into chunks](https://sqlite-utils.datasette.io/en/stable/reference.html#reference-utils-chunks). ([451](https://github.com/simonw/sqlite-utils/issues/451))
- `sqlite-utils enable-fts` now has a `--replace` option for replacing the existing FTS configuration for a table. ([450](https://github.com/simonw/sqlite-utils/issues/450))
- The `create-index`, `add-column` and `duplicate` commands all now take a `--ignore` option for ignoring errors should the database not be in the right state for them to operate. ([450](https://github.com/simonw/sqlite-utils/issues/450))

See also [the annotated release notes](https://simonwillison.net/2022/Jun/19/weeknotes/#sqlite-utils-3-27) for this release.

- Documentation now uses the [Furo](https://github.com/pradyunsg/furo) Sphinx theme. ([#435](https://github.com/simonw/sqlite-utils/issues/435))
- Code examples in documentation now have a "copy to clipboard" button. ([436](https://github.com/simonw/sqlite-utils/issues/436))
- `sqlite_utils.utils.utils.rows_from_file()` is now a documented API, see [Reading rows from a file](https://sqlite-utils.datasette.io/en/stable/python-api.html#python-api-rows-from-file). ([443](https://github.com/simonw/sqlite-utils/issues/443))
- `rows_from_file()` has two new parameters to help handle CSV files with rows that contain more values than are listed in that CSV file's headings: `ignore_extras=True` and `extras_key="name-of-key"`. ([440](https://github.com/simonw/sqlite-utils/issues/440))
- `sqlite_utils.utils.maximize_csv_field_size_limit()` helper function for increasing the field size limit for reading CSV files to its maximum, see [Setting the maximum CSV field size limit](https://sqlite-utils.datasette.io/en/stable/python-api.html#python-api-maximize-csv-field-size-limit). ([442](https://github.com/simonw/sqlite-utils/issues/442))
- `table.search(where=, where_args=)` parameters for adding additional `WHERE` clauses to a search query. The `where=` parameter is available on `table.search_sql(...)` as well. See [Searching with table.search()](https://sqlite-utils.datasette.io/en/stable/python-api.html#python-api-fts-search). ([441](https://github.com/simonw/sqlite-utils/issues/441))
- Fixed bug where `table.detect_fts()` and other search-related functions could fail if two FTS-enabled tables had names that were prefixes of each other. ([434](https://github.com/simonw/sqlite-utils/issues/434))