Loading sqliteimport

sqliteimport must be imported and configured before packages stored in sqlite can be imported. There are two considerations:

  1. When and where sqliteimport is imported

  2. How the path to the sqlite database is configured

Table of contents

Automatic everything

The simplest way to import sqliteimport and configure a database of packages is to create a custom sitecustomize module and set the PYTHONPATH environment variable.

This technique allows a database of packages to be used without modifying any application code.

sitecustomize.py
import sqliteimport
Linux/macOS
export PYTHONPATH='path/to/packages.sqlite3'
Windows Powershell
$env:PYTHONPATH='path/to/packages.sqlite3'

Note

sitecustomize.py must be in a directory that Python’s site module automatically searches. Please read the Python site module documentation for full details.

Warning

This technique may fail under some circumstances.

For example, Python interpreters installed by Homebrew include a custom sitecustomize that will be found and used before any that are created in a virtual environment.

Examples

The examples below demonstrate how to use a sitecustomize.py file with a PYTHONPATH environment variable.

Linux/macOS
# Install sqliteimport in a virtual environment.
python -m venv demo-venv
source demo-venv/bin/activate
python -m pip install sqliteimport[cli]

# Install flake8 and bundle it into a database.
python -m pip install flake8 --target flake8/
sqliteimport bundle flake8/ flake8.sqlite3
rm -rf flake8/

# Create a `sitecustomize.py` file.
site_packages_directory="$(python -c 'import site; print(site.getsitepackages()[0])')"
echo "Creating a sitecustomize.py file in ${site_packages_directory}"
echo 'import sqliteimport' > "${site_packages_directory}/sitecustomize.py"

# Point PYTHONPATH at the database.
export PYTHONPATH="flake8.sqlite3"

# Run flake8, and show where it's imported from.
python -m flake8 --version
python -c 'import flake8; print(f"Imported flake8 from {flake8.__file__!r}")'
Windows Powershell
# Install sqliteimport in a virtual environment.
python -m venv demo-venv
& ./demo-venv/bin/Activate.ps1
python -m pip install 'sqliteimport[cli]'

# Install flake8 and bundle it into a database.
python -m pip install flake8 --target flake8/
sqliteimport bundle flake8/ flake8.sqlite3
Remove-Item -Recurse -Force flake8/

# Create a `sitecustomize.py` file.
$site_packages_directory=python -c 'import site; print(site.getsitepackages()[0])'
Write-Host "Creating a sitecustomize.py file in ${site_packages_directory}"
Write-Output 'import sqliteimport' > "${site_packages_directory}/sitecustomize.py"

# Point PYTHONPATH at the database.
$env:PYTHONPATH="flake8.sqlite3"

# Run flake8, and show where it's imported from.
python -m flake8 --version
python -c 'import flake8; print(f"Imported flake8 from {flake8.__file__!r}")'

Manual imports

In some circumstances it may be helpful, or even necessary, to import sqliteimport in your application code. The obvious requirement is that sqliteimport must be imported before any packages that are bundled in a sqlite database.

Linters that sort Python imports may move import sqliteimport and prevent your code from executing. See the Integrating with isort and Integrating with ruff pages for suggestions how to configure those linters.

Manual database loading

If you cannot configure or control the PYTHONPATH environment variable to point to a sqlite database, you’ll need to load a database manually.

This is accomplished by calling sqliteimport.load() with a path to the database, represented as either a string or pathlib.Path instance.

import sqliteimport

sqliteimport.load("path/to/packages.sqlite3")

import example_package_from_database