Documentation tweaks

Author: rogerbinns

apsw/__init__.pyi

@@ -1959,11 +1959,11 @@ class Connection:
     def load_extension(self, filename: str, entrypoint: str | None = None) -> None:
         """Loads *filename* as an `extension <https://www.sqlite.org/loadext.html>`_
 
-        :param filename: The file to load.
+        :param filename: The file to load, the extension is optional
 
         :param entrypoint: The initialization method to call.  If this
-          parameter is not supplied then the SQLite default of
-          ``sqlite3_extension_init`` is used.
+          parameter is not supplied, then SQLite tries :code:`sqlite3_extension_init`
+          and a name derived from the filename.
 
         :raises ExtensionLoadingError: If the extension could not be
           loaded.  The exception string includes more details.
@@ -1972,7 +1972,8 @@ class Connection:
 
         .. seealso::
 
-          * :meth:`~Connection.enable_load_extension`"""
+          * :meth:`~Connection.enable_load_extension`
+          * :func:`apsw.sqlite_extra.load`"""
         ...
 
     loadextension = load_extension ## OLD-NAME
@@ -6792,11 +6793,11 @@ class AsyncConnection:
     async def load_extension(self, filename: str, entrypoint: str | None = None) -> None:
         """Loads *filename* as an `extension <https://www.sqlite.org/loadext.html>`_
 
-        :param filename: The file to load.
+        :param filename: The file to load, the extension is optional
 
         :param entrypoint: The initialization method to call.  If this
-          parameter is not supplied then the SQLite default of
-          ``sqlite3_extension_init`` is used.
+          parameter is not supplied, then SQLite tries :code:`sqlite3_extension_init`
+          and a name derived from the filename.
 
         :raises ExtensionLoadingError: If the extension could not be
           loaded.  The exception string includes more details.
@@ -6805,7 +6806,8 @@ class AsyncConnection:
 
         .. seealso::
 
-          * :meth:`~Connection.enable_load_extension`"""
+          * :meth:`~Connection.enable_load_extension`
+          * :func:`apsw.sqlite_extra.load`"""
         ...
 
     open_flags: int

apsw/shell.py

@@ -2185,8 +2185,8 @@ def command_load(self, cmd):
         Note: Extension loading may not be enabled in the SQLite
         library version you are using.
 
-        By default sqlite3_extension_init is called in the library but
-        you can specify an alternate entry point.
+        By default sqlite3_extension_init and a name derived from the filename
+        is tried, or you can specify an alternate entry point.
 
         If you get an error about the extension not being found you
         may need to explicitly specify the directory.  For example if
@@ -2195,7 +2195,7 @@ def command_load(self, cmd):
           .load ./extension
 
         :doc:`sqlite_extra <extra>` will also be searched for
-        extensions if the parameter is not found.  Use --list to see a
+        extensions if the file is not found.  Use --list to see a
         list available in this installation.
         """
         if len(cmd) < 1 or len(cmd) > 2:

apsw/sqlite_extra.py

@@ -18,7 +18,11 @@ class NotAvailable(Exception):
     pass
 
 def load(db: apsw.Connection, extension: str):
-    """Loads the extension into the provided database"""
+    """Loads the extension into the provided database
+
+    :meth:`Extension loading <apsw.Connection.enable_load_extension>` will
+    also be turned on.
+    """
     db.enable_load_extension(True)
     entry, path = _get_entry(extension)
     if entry["type"] != "extension":

doc/changes.rst

@@ -45,7 +45,9 @@ compiled.  These can be packaged with APSW for convenient access.  See
 Also included is the experimental under development `vec1 vector
 search extension <https://sqlite.org/vec1>`__.
 
-Added :meth:`Connection.reserve_bytes`.
+Added :meth:`Connection.reserve_bytes`.  This is useful for some of
+the :doc:`extras <extra>` like the `checksum VFS
+<https://sqlite.org/cksumvfs.html>`__.
 
 Fix wrapping, indents. and space for hyphens in
 :func:`apsw.unicode.text_wrap` under various conditions (:issue:`600`)

doc/cli.rst

@@ -553,18 +553,17 @@ Loads a SQLite extension library
 Note: Extension loading may not be enabled in the SQLite library version you are
 using.
 
-By default sqlite3_extension_init is called in the library but you can specify
-an alternate entry point.
+By default sqlite3_extension_init and a name derived from the filename is tried,
+or you can specify an alternate entry point.
 
 If you get an error about the extension not being found you may need to
 explicitly specify the directory.  For example if it is in the current directory
 then use::
 
   .load ./extension
 
-:doc:`sqlite_extra <extra>` will also be searched for extensions if the
-parameter is not found.  Use --list to see a list available in this
-installation.
+:doc:`sqlite_extra <extra>` will also be searched for extensions if the file is
+not found.  Use --list to see a list available in this installation.
 
 
 .log ON|OFF

doc/shell.rst

@@ -509,18 +509,17 @@ load FILE ?ENTRY?
 Note: Extension loading may not be enabled in the SQLite library version you are
 using.
 
-By default sqlite3_extension_init is called in the library but you can specify
-an alternate entry point.
+By default sqlite3_extension_init and a name derived from the filename is tried,
+or you can specify an alternate entry point.
 
 If you get an error about the extension not being found you may need to
 explicitly specify the directory.  For example if it is in the current directory
 then use::
 
   .load ./extension
 
-:doc:`sqlite_extra <extra>` will also be searched for extensions if the
-parameter is not found.  Use --list to see a list available in this
-installation.
+:doc:`sqlite_extra <extra>` will also be searched for extensions if the file is
+not found.  Use --list to see a list available in this installation.
 
 .. _shell-cmd-log:
 .. index::

doc/sqlite_extra.rst-inc

@@ -286,7 +286,7 @@ Extensions
         * Function: uuid uuid_blob uuid_str
 
     * - vec1
-      - `link <https://sqlite.org/vec1/doc/trunk/doc/vec1intro.md>`__
+      - `link <https://sqlite.org/vec1>`__
       - Vector search.  !Experimental! !Under development! Loading on before 2013 CPU may crash process
       -
         * Function: vec1_cos_distance vec1_from_json vec1_info vec1_l2_distance vec1_qinstr vec1_test_pq_decode vec1_test_pq_distortion vec1_test_pq_encode vec1_to_json vec1_to_json_f vec1_to_json_i vec1_train

src/apsw.docstrings

@@ -2327,11 +2327,11 @@
 #define  Connection_load_extension_DOC "Connection.load_extension(filename: str, entrypoint: str | None = None) -> None\n\n" \
 "Loads *filename* as an `extension <https://www.sqlite.org/loadext.html>`_\n" \
 "\n" \
-":param filename: The file to load.\n" \
+":param filename: The file to load, the extension is optional\n" \
 "\n" \
 ":param entrypoint: The initialization method to call.  If this\n" \
-"  parameter is not supplied then the SQLite default of\n" \
-"  ``sqlite3_extension_init`` is used.\n" \
+"  parameter is not supplied, then SQLite tries :code:`sqlite3_extension_init`\n" \
+"  and a name derived from the filename.\n" \
 "\n" \
 ":raises ExtensionLoadingError: If the extension could not be\n" \
 "  loaded.  The exception string includes more details.\n" \
@@ -2340,7 +2340,8 @@
 "\n" \
 ".. seealso::\n" \
 "\n" \
-"  * :meth:`~Connection.enable_load_extension`\n" 
+"  * :meth:`~Connection.enable_load_extension`\n" \
+"  * :func:`apsw.sqlite_extra.load`\n" 
 
 #define Connection_load_extension_KWNAMES "filename", "entrypoint"
 #define Connection_load_extension_USAGE "Connection.load_extension(filename: str, entrypoint: str | None = None) -> None"

src/connection.c

@@ -2915,11 +2915,11 @@ Connection_enable_load_extension(PyObject *self_, PyObject *const *fast_args, Py
 
   Loads *filename* as an `extension <https://www.sqlite.org/loadext.html>`_
 
-  :param filename: The file to load.
+  :param filename: The file to load, the extension is optional
 
   :param entrypoint: The initialization method to call.  If this
-    parameter is not supplied then the SQLite default of
-    ``sqlite3_extension_init`` is used.
+    parameter is not supplied, then SQLite tries :code:`sqlite3_extension_init`
+    and a name derived from the filename.
 
   :raises ExtensionLoadingError: If the extension could not be
     loaded.  The exception string includes more details.
@@ -2929,6 +2929,7 @@ Connection_enable_load_extension(PyObject *self_, PyObject *const *fast_args, Py
   .. seealso::
 
     * :meth:`~Connection.enable_load_extension`
+    * :func:`apsw.sqlite_extra.load`
 */
 static PyObject *
 Connection_load_extension(PyObject *self_, PyObject *const *fast_args, Py_ssize_t fast_nargs, PyObject *fast_kwnames)