carray doc tweaks

Author: rogerbinns

doc/changes.rst

@@ -54,7 +54,7 @@ It allows :meth:`binding single dimension packed arrays <apsw.carray>`
 of 32/64 bit integers, or 64 bit floats.  For example these can come
 from :mod:`array`, `numpy arrays
 <https://numpy.org/doc/stable/reference/generated/numpy.array.html>`__
-or binary data.
+or binary data.  See the :ref:`example <example_carray>`.
 
 ``SQLITE_SCM_`` constants (``BRANCH``, ``TAGS``, ``DATETIME``) are available
 on the module if built with the :attr:`amalgamation <using_amalgamation>`.

doc/extensions.rst

@@ -10,16 +10,41 @@ functionality.  All extensions are disabled by default and you need to
 :ref:`take steps <setup_build_flags>` to have them available at compilation
 time, to enable them and then to use them.
 
-If you get APSW from PyPI or are using SQLite from your Linux/BSD platform
-then they all enabled usually.
+If you get APSW from PyPI they are all enabled.  If APSW comes from
+your Linux/BSD platform then it will match your platform
+configuration.
+
+CARRAY
+======
+
+`Runtime array of values extension <https://sqlite.org/carray.html>`__ used
+with :meth:`apsw.carray`.
+
+Session
+=======
+
+:doc:`session`
+
+Math functions
+==============
+
+Several `SQL functions <https://sqlite.org/lang_mathfunc.html>`__
+
+Percentile (media)
+==================
+
+Several `SQL functions <https://sqlite.org/percentile.html>`__ related
+to `percentiles <https://en.wikipedia.org/wiki/Percentile>`__.  Python
+has a :mod:`statistics` module with some of the same functions, but
+this extension is more convenient.
 
 .. _ext-fts3:
 
 FTS5
 ====
 
 `FTS5 <https://www.sqlite.org/fts5.html>`__ is the full text search extension.
-APSW includes comprehensive :doc:`functionality  <textsearch>`..
+APSW includes comprehensive :doc:`functionality  <textsearch>`.
 
 .. _ext-icu:
 
@@ -42,3 +67,4 @@ The RTree extension provides a `spatial table
 <https://en.wikipedia.org/wiki/R-tree>`_ - see the `documentation
 <https://sqlite.org/rtree.html>`__.  There are no additional APIs and
 the `documented SQL <https://sqlite.org/rtree.html>`__ works as is.
+

examples/main.py

@@ -103,13 +103,13 @@
 # a simple value
 event = "system started"
 # DO NOT DO THIS
-query = f"insert into log values(0, '{ event }')"
+query = f"insert into log values(0, '{event}')"
 print("query:", query)
 
 # BECAUSE ... a bad guy could provide a value like this
 event = "bad guy here') ; drop table important; -- comment"
 # which has effects like this
-query = f"insert into log values(0, '{ event }')"
+query = f"insert into log values(0, '{event}')"
 print("bad guy:", query)
 
 ### bindings_sequence: Bindings (sequence)
@@ -277,7 +277,7 @@ def row_tracer(
 
 def ilove7(*args: apsw.SQLiteValue) -> int:
     "A scalar function"
-    print(f"ilove7 got { args } but I love 7")
+    print(f"ilove7 got {args} but I love 7")
     return 7
 
 
@@ -489,7 +489,7 @@ def __init__(self, x, y):
         self.y = y
 
     def __repr__(self) -> str:
-        return f"Point({ self.x }, { self.y })"
+        return f"Point({self.x}, {self.y})"
 
     def __eq__(self, other: object) -> bool:
         return (
@@ -500,7 +500,7 @@ def __eq__(self, other: object) -> bool:
 
     def to_sqlite_value(self) -> str:
         # called to convert Point into something SQLite supports
-        return f"{ self.x };{ self.y }"
+        return f"{self.x};{self.y}"
 
     # This converter will be registered
     @classmethod
@@ -510,7 +510,7 @@ def convert_from_sqlite(cls, value: str) -> Point:
 
 # Existing types
 def complex_to_sqlite_value(c: complex) -> str:
-    return f"{ c.real }+{ c.imag }"
+    return f"{c.real}+{c.imag}"
 
 
 def datetime_to_sqlite_value(dt: datetime.datetime) -> float:
@@ -561,7 +561,7 @@ def sqlite_to_datetime(v: float) -> datetime.datetime:
 print("querying data")
 for row in connection.execute("select * from conversion"):
     for i, value in enumerate(row):
-        print(f"column {i} = { value !r}")
+        print(f"column {i} = {value!r}")
 
 # clear registrar
 connection.cursor_factory = apsw.Cursor
@@ -657,7 +657,9 @@ def make_set(*args):
     ):
         pass
 
-print(f"After {time.monotonic() - start:.3f} seconds, we hit {number=}")
+print(
+    f"After {time.monotonic() - start:.3f} seconds, we hit {number=}"
+)
 
 # We used the default "no exception" exception.  Lets have an explicit exception.
 # with both row and time limits ...
@@ -941,7 +943,7 @@ def my_update_hook(
 ) -> None:
     op: str = apsw.mapping_authorizer_function[type]
     print(
-        f"Updated: { op } db { db_name }, table { table_name }, rowid { rowid }"
+        f"Updated: {op} db {db_name}, table {table_name}, rowid {rowid}"
     )
 
 
@@ -1191,7 +1193,7 @@ def xFileControl(self, op: int, ptr: int) -> bool:
             return super().xFileControl(op, ptr)
         # implement our own pragma
         p = apsw.VFSFcntlPragma(ptr)
-        print(f"pragma received { p.name } = { p.value }")
+        print(f"pragma received {p.name} = {p.value}")
         # what do we understand?
         if p.name == "my_custom_pragma":
             p.result = "orange"
@@ -1323,11 +1325,9 @@ def xFileControl(self, op: int, ptr: int) -> bool:
 # for per connection statistics.
 
 current_usage, max_usage = apsw.status(apsw.SQLITE_STATUS_MEMORY_USED)
-print(f"SQLite memory usage { current_usage } max { max_usage }")
+print(f"SQLite memory usage {current_usage} max {max_usage}")
 schema_used, _ = connection.status(apsw.SQLITE_DBSTATUS_SCHEMA_USED)
-print(
-    f"{ schema_used } bytes used to store schema for this connection"
-)
+print(f"{schema_used} bytes used to store schema for this connection")
 
 ### trace_v2: Tracing
 # This shows using :meth:`Connection.trace_v2`
@@ -1424,7 +1424,9 @@ def trace_hook(trace: dict) -> None:
 
     # pragma functions are virtual tables - see how many rows this processes even
     # though only one has 'pow'
-    connection.execute("SELECT narg FROM pragma_function_list WHERE name='pow'").get
+    connection.execute(
+        "SELECT narg FROM pragma_function_list WHERE name='pow'"
+    ).get
 
     # trigger that causes rollback
     connection.execute("""
@@ -1499,12 +1501,12 @@ def trace_hook(trace: dict) -> None:
 # See values before change
 print("Before values")
 print(f'{connection.pragma("schema_version")=}')
-print(f'{connection.data_version()=}')
+print(f"{connection.data_version()=}")
 
 print("\nAfter values")
 # add to table from previous section
 con2.execute("insert into dummy values(1, 2, 3)")
-print(f'{connection.data_version()=}')
+print(f"{connection.data_version()=}")
 
 # and add a table.  changing an existing table definition etc also
 # bump the schema version

src/apsw.c

@@ -292,33 +292,21 @@ static int allow_missing_dict_bindings = 0;
 
   Indicates a Python object is being provided as a runtime array for the
   `Carray extension <https://sqlite.org/carray.html>`__.  This is useful if you
-  need a number of numbers (int or float), strings, or blobs available during a query,
+  need many numbers (int or float), strings, or blobs available during a query,
   You can avoid temporary tables, formatting SQL with corresponding numbers of ``?``,
   and the array will be used without calling back into Python code or acquiring the GIL.
 
-  .. code-block:: python
-
-    import array
-
-    # packed array of 32 bit int
-    ids = array.array("i", [1, 73, 94567, 62])
-
-    # get records matching those ids
-    for row in con.execute("SELECT * FROM record WHERE record.id IN CARRAY(?)",
-      apsw.carray(ids)):
-      print(row)
+  See the :ref:`example <example_carray>`.
 
   :param object: For numbers, any object that implements the buffer protocol as
      a single contiguous binary data like :class:`bytes`, :class:`bytearray`,
      :class:`array.array`, numpy.array etc.
 
      Otherwise it should be a tuple of strings, or a tuple of binary data
      objects.
-
   :param start: Index of the first entry to bind
   :param stop: Index to stop at - ie one beyond the last entry bound.  Default
-      is all remaining members.  There is a limit of 2 billion, and a minimum
-      of 1.
+      is all remaining members.
   :param flags: Default auto detect.
 
       For numbers, detection is done from the buffer
@@ -345,8 +333,10 @@ static int allow_missing_dict_bindings = 0;
       and :code:`apsw.SQLITE_CARRAY_BLOB` respectively, but they would be detected anyway.
       A wrong value will fail.
 
-  Carray support is only present if APSW was compiled with ``SQLITE_ENABLE_CARRAY`` such as
-  PyPi builds.
+  .. note::
+
+    Carray support is only present if APSW was compiled with ``SQLITE_ENABLE_CARRAY`` such as
+    PyPi builds.  The array must have at least one member and at most 2 billion.
 */
 
 /** .. method:: sqlite_lib_version() -> str