Make the docstring examples runnable doctests against real LMFDB sample data

psycodict/__init__.py

@@ -3,26 +3,32 @@
 This module provides an interface to Postgres supporting
 the kinds of queries needed by the LMFDB.
 
+The examples in this package's docstrings are real transcripts, run as
+doctests by ``tests/test_doctests.py`` against two small tables of LMFDB
+data that it creates: ``test_fields`` (22 selected number fields of
+degree at most 3) and ``test_curves`` (a dozen elliptic curves over three
+of those fields).
+
 EXAMPLES::
 
-    sage: from lmfdb import db
-    sage: db
+    >>> from psycodict.database import PostgresDatabase
+    >>> db = PostgresDatabase()  # configuration found via $PSYCODICT_CONFIG / config.ini
+    >>> db
     Interface to Postgres database
-    sage: len(db.tablenames)
-    53
-    sage: db.tablenames[0]
-    'artin_field_data'
-    sage: db.artin_field_data
-    Interface to Postgres table artin_field_data
+    >>> 'test_fields' in db.tablenames
+    True
+    >>> nf = db.test_fields
+    >>> nf
+    Interface to Postgres table test_fields
 
 You can search using the methods ``search``, ``lucky`` and ``lookup``::
 
-    sage: G = db.gps_groups.lookup('8.2')
-    sage: G['exponent']
-    4
-
-- ``count_table`` -- a string or None.  If provided, gives the name of a table that caches counts for searches on the search table.  These counts are relevant when many results are returned, allowing the search pages to report the number of records even when it would take Postgres a long time to compute this count.
-
+    >>> nf.lookup('2.0.23.1', 'class_number')
+    3
+    >>> nf.lucky({'degree': 2, 'disc_sign': 1, 'disc_abs': 5}, projection=0)
+    '2.2.5.1'
+    >>> list(nf.search({'ramps': {'$contains': [2]}}, projection=0))
+    ['2.0.4.1', '2.0.8.1', '2.2.8.1', '2.2.12.1', '3.1.44.1', '3.1.76.1']
 """
 
 # Single source of truth for the package version: pyproject.toml reads it via

psycodict/base.py

@@ -827,24 +827,20 @@ def _column_types(self, table_name, data_types=None):
 
         EXAMPLES::
 
-            sage: db._column_types('non_existant')
+            >>> db._column_types('nonexistent')
             ([], {}, False)
-            sage: db._column_types('test_table')
-            (['dim',
-              'label',
-              'discriminant',
-              'bad_primes',
-              'new_column1',
-              'new_label',
-              'bar'],
-             {'bad_primes': 'jsonb',
-              'bar': 'text',
-              'dim': 'smallint',
-              'discriminant': 'numeric',
-              'id': 'bigint',
-              'label': 'text',
-              'new_column1': 'text',
-              'new_label': 'text'},
+            >>> db._column_types('test_fields')
+            (['class_group', 'class_number', 'degree', 'disc_abs',
+              'disc_sign', 'label', 'r2', 'ramps'],
+             {'id': 'bigint',
+              'class_number': 'integer',
+              'disc_abs': 'integer',
+              'degree': 'smallint',
+              'disc_sign': 'smallint',
+              'r2': 'smallint',
+              'ramps': 'integer[]',
+              'class_group': 'jsonb',
+              'label': 'text'},
              True)
         """
         has_id = False

psycodict/database.py

@@ -179,15 +179,14 @@ class PostgresDatabase(PostgresBase):
 
     EXAMPLES::
 
-        sage: from lmfdb import db
-        sage: db
+        >>> db
         Interface to Postgres database
-        sage: db.conn
-        <connection object at 0x...>
-        sage: db.tablenames[:3]
-        ['artin_field_data', 'artin_reps', 'av_fqisog']
-        sage: db.av_fqisog
-        Interface to Postgres table av_fqisog
+        >>> db.conn
+        <psycopg.Connection [IDLE] (host=... database=...) at 0x...>
+        >>> 'test_fields' in db.tablenames
+        True
+        >>> db.test_fields
+        Interface to Postgres table test_fields
     """
     # Override the following to use a different class for search tables
     _search_table_class_ = PostgresSearchTable
@@ -1829,18 +1828,18 @@ def compare(self, other, tables=None, row_counts=True, null_counts=False, exact=
 
         Comparing with a server described by a second configuration file::
 
-            sage: from psycodict.config import Configuration
-            sage: from psycodict.database import PostgresDatabase
-            sage: prod_config = Configuration(defaults={"config_file": "prod-config.ini"}, readargs=False)
-            sage: prod = PostgresDatabase(config=prod_config)
-            sage: db.compare(prod)["only_in_self"]
+            >>> from psycodict.config import Configuration
+            >>> from psycodict.database import PostgresDatabase
+            >>> prod_config = Configuration(defaults={"config_file": "prod-config.ini"}, readargs=False)  # doctest: +SKIP
+            >>> prod = PostgresDatabase(config=prod_config)  # doctest: +SKIP
+            >>> db.compare(prod)["only_in_self"]  # doctest: +SKIP
             ['mf_newspaces_test']
 
         Keyword arguments override the configuration, so a server that
         differs only in its host can reuse this database's configuration::
 
-            sage: prod = PostgresDatabase(config=db.config, host="proddb.lmfdb.xyz")
-            sage: db.compare(prod, tables="mf_newspaces", null_counts=True)
+            >>> prod = PostgresDatabase(config=db.config, host="proddb.lmfdb.xyz")  # doctest: +SKIP
+            >>> db.compare(prod, tables="mf_newspaces", null_counts=True)  # doctest: +SKIP
             {'only_in_self': [], 'only_in_other': [], 'schema': {}, 'row_counts': {}, 'null_counts': {}}
         """
         from .dbdiff import compare_databases

psycodict/encoding.py

@@ -137,7 +137,7 @@ def numeric_precision(value):
 
     EXAMPLES::
 
-        sage: numeric_precision("0.00459244230167")  # 12 significant digits
+        >>> numeric_precision("0.00459244230167")  # 12 significant digits
         40
     """
     digits = len(value.lstrip("+-").replace(".", "", 1).lstrip("0"))