release

rogerbinns · Jun 16, 2024 · f909ff4 · f909ff4
1 parent 2b7f548
commit f909ff4
Show file tree

Hide file tree

Showing 41 changed files with 853 additions and 649 deletions.
diff --git a/.buildinfo b/.buildinfo
@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 7928e2fd7a314e3ac6de9b2b2bfb9cbe
+config: 78dd931ab72ab9cfa9d2e437788cfbdd
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/_modules/apsw/bestpractice.html b/_modules/apsw/bestpractice.html
@@ -3,7 +3,7 @@
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>apsw.bestpractice &mdash; APSW 3.46.0.0 documentation</title>
+  <title>apsw.bestpractice &mdash; APSW 3.46.0.1 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=72bcf2f2" />
       <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=19f00094" />
       <link rel="stylesheet" type="text/css" href="../../_static/apsw.css?v=3c7e2631" />
@@ -16,7 +16,7 @@
 
         <script src="../../_static/jquery.js?v=5d32c60e"></script>
         <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script src="../../_static/documentation_options.js?v=7df7d932"></script>
+        <script src="../../_static/documentation_options.js?v=d98f5d2b"></script>
         <script src="../../_static/doctools.js?v=9a2dae69"></script>
         <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../../_static/js/theme.js"></script>
@@ -39,7 +39,7 @@
               <img src="../../_static/apswlogo.png" class="logo" alt="Logo"/>
           </a>
               <div class="version">
-                3.46.0.0
+                3.46.0.1
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
@@ -219,7 +219,7 @@ <h1>Source code for apsw.bestpractice</h1><div class="highlight"><pre>
 
   <div role="contentinfo">
     <p>&#169; <a href="../../copyright.html">Copyright</a> 2004-2024, Roger Binns &lt;[email protected]&gt;.
-      <span class="lastupdated">Last updated on May 23, 2024.
+      <span class="lastupdated">Last updated on Jun 16, 2024.
       </span></p>
   </div>
 

diff --git a/_modules/apsw/ext.html b/_modules/apsw/ext.html
diff --git a/_modules/apsw/shell.html b/_modules/apsw/shell.html
@@ -3,7 +3,7 @@
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>apsw.shell &mdash; APSW 3.46.0.0 documentation</title>
+  <title>apsw.shell &mdash; APSW 3.46.0.1 documentation</title>
       <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=72bcf2f2" />
       <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=19f00094" />
       <link rel="stylesheet" type="text/css" href="../../_static/apsw.css?v=3c7e2631" />
@@ -16,7 +16,7 @@
 
         <script src="../../_static/jquery.js?v=5d32c60e"></script>
         <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script src="../../_static/documentation_options.js?v=7df7d932"></script>
+        <script src="../../_static/documentation_options.js?v=d98f5d2b"></script>
         <script src="../../_static/doctools.js?v=9a2dae69"></script>
         <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../../_static/js/theme.js"></script>
@@ -39,7 +39,7 @@
               <img src="../../_static/apswlogo.png" class="logo" alt="Logo"/>
           </a>
               <div class="version">
-                3.46.0.0
+                3.46.0.1
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
@@ -975,13 +975,20 @@ <h1>Source code for apsw.shell</h1><div class="highlight"><pre>
             <span class="n">cur</span><span class="o">.</span><span class="n">execute</span><span class="p">(</span><span class="n">sql</span><span class="p">,</span> <span class="n">bindings</span><span class="p">)</span>
         <span class="k">except</span> <span class="n">apsw</span><span class="o">.</span><span class="n">ExecTraceAbort</span><span class="p">:</span>
             <span class="k">pass</span>
+        <span class="k">except</span> <span class="n">apsw</span><span class="o">.</span><span class="n">BindingsError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
+            <span class="k">return</span> <span class="n">Shell</span><span class="o">.</span><span class="n">_qd</span><span class="p">(</span><span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="s2">&quot;You must used named bindings (eg $name) and .parameter set&quot;</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="n">e</span><span class="p">,</span> <span class="n">explain</span><span class="p">)</span>
         <span class="k">except</span> <span class="n">apsw</span><span class="o">.</span><span class="n">Error</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
-            <span class="k">return</span> <span class="n">Shell</span><span class="o">.</span><span class="n">_qd</span><span class="p">(</span><span class="n">sql</span><span class="p">[:</span><span class="nb">len</span><span class="p">(</span><span class="n">saved</span><span class="p">)],</span> <span class="n">sql</span><span class="p">[</span><span class="nb">len</span><span class="p">(</span><span class="n">saved</span><span class="p">):],</span> <span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">),</span> <span class="n">e</span><span class="o">.</span><span class="n">error_offset</span><span class="p">,</span> <span class="n">e</span><span class="p">,</span> <span class="n">explain</span><span class="p">)</span>
+            <span class="k">return</span> <span class="n">Shell</span><span class="o">.</span><span class="n">_qd</span><span class="p">(</span><span class="n">sql</span><span class="p">[:</span> <span class="nb">len</span><span class="p">(</span><span class="n">saved</span><span class="p">)],</span> <span class="n">sql</span><span class="p">[</span><span class="nb">len</span><span class="p">(</span><span class="n">saved</span><span class="p">)</span> <span class="p">:],</span> <span class="nb">str</span><span class="p">(</span><span class="n">e</span><span class="p">),</span> <span class="nb">getattr</span><span class="p">(</span><span class="n">e</span><span class="p">,</span> <span class="s2">&quot;error_offset&quot;</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">),</span> <span class="n">e</span><span class="p">,</span> <span class="n">explain</span><span class="p">)</span>
         <span class="k">except</span> <span class="ne">KeyError</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span>
             <span class="n">var</span> <span class="o">=</span> <span class="n">e</span><span class="o">.</span><span class="n">args</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
-            <span class="k">return</span> <span class="n">Shell</span><span class="o">.</span><span class="n">_qd</span><span class="p">(</span><span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span>
-                             <span class="sa">f</span><span class="s2">&quot;No binding present for &#39;</span><span class="si">{</span><span class="w"> </span><span class="n">var</span><span class="w"> </span><span class="si">}</span><span class="s2">&#39; - use .parameter set </span><span class="si">{</span><span class="w"> </span><span class="n">var</span><span class="w"> </span><span class="si">}</span><span class="s2"> VALUE to provide one&quot;</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">,</span>
-                             <span class="n">e</span><span class="p">,</span> <span class="n">explain</span><span class="p">)</span>
+            <span class="k">return</span> <span class="n">Shell</span><span class="o">.</span><span class="n">_qd</span><span class="p">(</span>
+                <span class="kc">None</span><span class="p">,</span>
+                <span class="kc">None</span><span class="p">,</span>
+                <span class="sa">f</span><span class="s2">&quot;No binding present for &#39;</span><span class="si">{</span><span class="w"> </span><span class="n">var</span><span class="w"> </span><span class="si">}</span><span class="s2">&#39; - use .parameter set </span><span class="si">{</span><span class="w"> </span><span class="n">var</span><span class="w"> </span><span class="si">}</span><span class="s2"> VALUE to provide one&quot;</span><span class="p">,</span>
+                <span class="o">-</span><span class="mi">1</span><span class="p">,</span>
+                <span class="n">e</span><span class="p">,</span>
+                <span class="n">explain</span><span class="p">,</span>
+            <span class="p">)</span>
         <span class="k">return</span> <span class="n">Shell</span><span class="o">.</span><span class="n">_qd</span><span class="p">(</span><span class="n">sql</span><span class="p">[:</span><span class="nb">len</span><span class="p">(</span><span class="n">saved</span><span class="p">)],</span> <span class="n">sql</span><span class="p">[</span><span class="nb">len</span><span class="p">(</span><span class="n">saved</span><span class="p">):],</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">,</span> <span class="n">explain</span><span class="p">)</span>
 
 <div class="viewcode-block" id="Shell.process_sql">
@@ -2840,10 +2847,10 @@ <h1>Source code for apsw.shell</h1><div class="highlight"><pre>
             <span class="bp">self</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">stdout</span><span class="p">,</span> <span class="s2">&quot; &quot;</span> <span class="o">*</span> <span class="p">(</span><span class="n">maxw</span> <span class="o">-</span> <span class="nb">len</span><span class="p">(</span><span class="n">k</span><span class="p">))</span> <span class="o">+</span> <span class="sa">f</span><span class="s2">&quot;</span><span class="si">{</span><span class="w"> </span><span class="n">k</span><span class="w"> </span><span class="si">}</span><span class="s2">  </span><span class="si">{</span><span class="w"> </span><span class="n">v</span><span class="si">}</span><span class="se">\n</span><span class="s2">&quot;</span><span class="p">)</span>
 
     <span class="k">def</span> <span class="nf">command_vfsname</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">cmd</span><span class="p">):</span>
-        <span class="s2">&quot;vfsname: VFS name used to open current database&quot;</span>
-        <span class="k">if</span> <span class="n">cmd</span><span class="p">:</span>
-            <span class="k">raise</span> <span class="bp">self</span><span class="o">.</span><span class="n">Error</span><span class="p">(</span><span class="s2">&quot;No parameters taken&quot;</span><span class="p">)</span>
-        <span class="bp">self</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">stdout</span><span class="p">,</span> <span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">open_vfs</span> <span class="o">+</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">&quot;</span><span class="p">)</span>
+        <span class="s2">&quot;vfsname: VFS name for database, or attached names&quot;</span>
+        <span class="n">dbnames</span> <span class="o">=</span> <span class="n">cmd</span> <span class="ow">or</span> <span class="p">[</span><span class="s2">&quot;main&quot;</span><span class="p">]</span>
+        <span class="k">for</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">dbnames</span><span class="p">:</span>
+            <span class="bp">self</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">stdout</span><span class="p">,</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">vfsname</span><span class="p">(</span><span class="n">name</span><span class="p">)</span> <span class="ow">or</span> <span class="s2">&quot;&quot;</span><span class="p">)</span> <span class="o">+</span> <span class="s2">&quot;</span><span class="se">\n</span><span class="s2">&quot;</span><span class="p">)</span>
 
     <span class="k">def</span> <span class="nf">_format_vfs</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">vfs</span><span class="p">):</span>
         <span class="n">w</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">k</span><span class="p">)</span> <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="n">vfs</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
@@ -3213,6 +3220,7 @@ <h1>Source code for apsw.shell</h1><div class="highlight"><pre>
         <span class="s2">&quot;optimize(&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
         <span class="s2">&quot;page_count;&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
         <span class="s2">&quot;page_size=&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
+        <span class="s2">&quot;pragma_list;&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
         <span class="s2">&quot;query_only=&quot;</span><span class="p">:</span> <span class="n">_pragmas_bool</span><span class="p">,</span>
         <span class="s2">&quot;quick_check&quot;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
         <span class="s2">&quot;read_uncommitted=&quot;</span><span class="p">:</span> <span class="n">_pragmas_bool</span><span class="p">,</span>
@@ -3700,7 +3708,7 @@ <h1>Source code for apsw.shell</h1><div class="highlight"><pre>
 
   <div role="contentinfo">
     <p>&#169; <a href="../../copyright.html">Copyright</a> 2004-2024, Roger Binns &lt;[email protected]&gt;.
-      <span class="lastupdated">Last updated on May 23, 2024.
+      <span class="lastupdated">Last updated on Jun 16, 2024.
       </span></p>
   </div>
 

diff --git a/_modules/index.html b/_modules/index.html
@@ -3,7 +3,7 @@
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Overview: module code &mdash; APSW 3.46.0.0 documentation</title>
+  <title>Overview: module code &mdash; APSW 3.46.0.1 documentation</title>
       <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=72bcf2f2" />
       <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
       <link rel="stylesheet" type="text/css" href="../_static/apsw.css?v=3c7e2631" />
@@ -16,7 +16,7 @@
 
         <script src="../_static/jquery.js?v=5d32c60e"></script>
         <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
-        <script src="../_static/documentation_options.js?v=7df7d932"></script>
+        <script src="../_static/documentation_options.js?v=d98f5d2b"></script>
         <script src="../_static/doctools.js?v=9a2dae69"></script>
         <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="../_static/js/theme.js"></script>
@@ -39,7 +39,7 @@
               <img src="../_static/apswlogo.png" class="logo" alt="Logo"/>
           </a>
               <div class="version">
-                3.46.0.0
+                3.46.0.1
               </div>
 <div role="search">
   <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
@@ -114,7 +114,7 @@ <h1>All modules for which code is available</h1>
 
   <div role="contentinfo">
     <p>&#169; <a href="../copyright.html">Copyright</a> 2004-2024, Roger Binns &lt;[email protected]&gt;.
-      <span class="lastupdated">Last updated on May 23, 2024.
+      <span class="lastupdated">Last updated on Jun 16, 2024.
       </span></p>
   </div>
 

diff --git a/_sources/changes.rst.txt b/_sources/changes.rst.txt
@@ -10,6 +10,27 @@ history <https://devguide.python.org/versions/>`__.
 APSW changes by version
 -----------------------
 
+3.46.0.1
+========
+
+:func:`apsw.ext.query_info` provides the count and names of bindings
+parameters.  (:issue:`528`)
+
+Address how errors are handled in VFS xRandomness routine, that is
+only called once by SQLite to seed its random number generator.
+(:issue:`526`)
+
+Added :meth:`Connection.vfsname` and updated corresponding shell
+command to get the diagnostic names of the vfs stack for the
+connection.  (:issue:`525`)
+
+Do not cache :meth:`Connection.pragma` statements to avoid encryption
+keys, or pragmas that run during prepare from being retained.
+(:issue:`522`)
+
+:meth:`Connection.pragma` adds keyword ``schema`` argument to run
+pragma against attached databases.  (:issue:`524`)
+
 3.46.0.0
 ========
 

diff --git a/_sources/connection.rst.txt b/_sources/connection.rst.txt
@@ -608,6 +608,9 @@ If `entries` is present, then each list entry is a dict with the following infor
     returns when the first row is available or all statements have
     completed.  (A cursor is automatically obtained).
 
+    For pragmas you should use :meth:`pragma` which handles quoting and
+    caching correctly.
+
     See :meth:`Cursor.execute` for more details, and the :ref:`example <example_executing_sql>`.
 
 .. method:: Connection.executemany(statements: str, sequenceofbindings:Iterable[Bindings], *, can_cache: bool = True, prepare_flags: int = 0, explain: int = -1) -> Cursor
@@ -817,7 +820,7 @@ See :meth:`Cursor.executemany` for more details, and the :ref:`example <example_
 
   Calls: `sqlite3_overload_function <https://sqlite.org/c3ref/overload_function.html>`__
 
-.. method:: Connection.pragma(name: str, value: Optional[SQLiteValue] = None) -> Any
+.. method:: Connection.pragma(name: str, value: Optional[SQLiteValue] = None, *, schema: Optional[str] = None) -> Any
 
   Issues the pragma (with the value if supplied) and returns the result with
   :attr:`the least amount of structure <Cursor.get>`.  For example
@@ -826,7 +829,13 @@ See :meth:`Cursor.executemany` for more details, and the :ref:`example <example_
   now in effect.
 
   Pragmas do not support bindings, so this method is a convenient
-  alternative to composing SQL text.
+  alternative to composing SQL text.  Pragmas are often executed
+  while being prepared, instead of when run like regular SQL.  They
+  may also contain encryption keys.  This method ensures they are
+  not cached to avoid problems.
+
+  Use the `schema` parameter to run the pragma against a different
+  attached database (eg ``temp``).
 
   * :ref:`Example <example_pragma>`
 
@@ -1183,6 +1192,20 @@ libraries.
 
   Calls: `sqlite3_txn_state <https://sqlite.org/c3ref/txn_state.html>`__
 
+.. method:: Connection.vfsname(dbname: str) -> str | None
+
+Issues the `SQLITE_FCNTL_VFSNAME
+<https://sqlite.org/c3ref/c_fcntl_begin_atomic_write.html#sqlitefcntlvfsname>`__
+file control against the named database (`main`, `temp`, attached
+name).
+
+This is useful to see which VFS is in use, and if inheritance is used
+then ``/`` will separate the names.  If you have a :class:`VFSFile` in
+use then its fully qualified class name will also be included.
+
+If ``SQLITE_FCNTL_VFSNAME`` is not implemented, ``dbname`` is not a
+database name, or an error occurred then ``None`` is returned.
+
 .. index:: sqlite3_vtab_config
 
 .. method:: Connection.vtab_config(op: int, val: int = 0) -> None