diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 5d69832..6419040 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -74,3 +74,11 @@ repos: rev: "v1.0.0" hooks: - id: "verify-consistent-pyproject-toml-python-requirements" + + - repo: "https://github.com/shellcheck-py/shellcheck-py" + rev: "v0.11.0.1" + hooks: + - id: "shellcheck" + args: [ + "-e", "SC1091", # Ignore non-existent 'source ...' targets. + ] diff --git a/changelog.d/20250921_122610_kurtmckee_doc_sitecustomize.rst b/changelog.d/20250921_122610_kurtmckee_doc_sitecustomize.rst new file mode 100644 index 0000000..a4da90c --- /dev/null +++ b/changelog.d/20250921_122610_kurtmckee_doc_sitecustomize.rst @@ -0,0 +1,9 @@ +Documentation +------------- + +* Document how to import sqliteimport and load a database of packages. + + This now includes runnable scripts showing fully-automated loading + using ``sitecustomize.py`` and the ``PYTHONPATH`` environment variable. + In addition, more information is provided + for manually importing sqliteimport and loading a database. diff --git a/docs/index.rst b/docs/index.rst index c268a4d..a1d41fe 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -55,7 +55,7 @@ Table of contents .. toctree:: :maxdepth: 1 - load + load/index bytecode flake8/index isort/index diff --git a/docs/load.rst b/docs/load.rst deleted file mode 100644 index 16773e2..0000000 --- a/docs/load.rst +++ /dev/null @@ -1,36 +0,0 @@ -.. - This file is a part of sqliteimport - Copyright 2024-2025 Kurt McKee - SPDX-License-Identifier: MIT - - -Loading sqliteimport -#################### - -sqliteimport must be imported and configured -before packages stored in sqlite can be imported. - - -Automatic loading -================= - -If you use the ``PYTHONPATH`` environment variable to point to a sqlite database -then importing sqliteimport is sufficient to load packages from the database. - - -.. code-block:: shell - :caption: Linux/macOS - - export PYTHONPATH=packages.sqlite3 - - python -m my_tool_or_package - ./my_tool_or_package - - -.. code-block:: powershell - :caption: Windows Powershell - - $env:PYTHONPATH="packages.sqlite3" - - python -m my_tool_or_package - & my_tool_or_package diff --git a/docs/load/assets/automatic.ps1 b/docs/load/assets/automatic.ps1 new file mode 100644 index 0000000..298e416 --- /dev/null +++ b/docs/load/assets/automatic.ps1 @@ -0,0 +1,21 @@ +# 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}")' diff --git a/docs/load/assets/automatic.sh b/docs/load/assets/automatic.sh new file mode 100644 index 0000000..9637282 --- /dev/null +++ b/docs/load/assets/automatic.sh @@ -0,0 +1,22 @@ +#!/usr/bin/env bash +# 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}")' diff --git a/docs/load/index.rst b/docs/load/index.rst new file mode 100644 index 0000000..fb9db2a --- /dev/null +++ b/docs/load/index.rst @@ -0,0 +1,123 @@ +.. + This file is a part of sqliteimport + Copyright 2024-2025 Kurt McKee + SPDX-License-Identifier: MIT + + +Loading sqliteimport +#################### + +sqliteimport must be imported and configured +before packages stored in sqlite can be imported. +There are two considerations: + +#. When and where sqliteimport is *imported* +#. How the path to the sqlite database is *configured* + +Table of contents +================= + +* :ref:`automatic` +* :ref:`manual-import` +* :ref:`manual-load` + + +.. _automatic: + +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*. + +.. code-block:: python + :caption: ``sitecustomize.py`` + + import sqliteimport + +.. code-block:: bash + :caption: Linux/macOS + + export PYTHONPATH='path/to/packages.sqlite3' + +.. code-block:: powershell + :caption: 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. + +.. literalinclude:: assets/automatic.sh + :caption: Linux/macOS + :language: bash + :lines: 2- + +.. literalinclude:: assets/automatic.ps1 + :caption: Windows Powershell + :language: powershell + + + +.. _manual-import: + +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 :doc:`../isort/index` and :doc:`../ruff/index` pages +for suggestions how to configure those linters. + + +.. _manual-load: + +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. + +.. code-block:: python + + import sqliteimport + + sqliteimport.load("path/to/packages.sqlite3") + + import example_package_from_database + + +.. Links +.. ----- +.. +.. _Python site module: https://docs.python.org/3/library/site.html