Tests: Refactor SQLAlchemy-related doctests into documentation

- doctests/sqlalchemy.rst
- sqlalchemy/doctests/{dialect,itests,reflection}.txt

docs/by-example/index.rst

@@ -10,6 +10,15 @@ About
 This part of the documentation contains examples how to use the CrateDB Python
 client, exercising different options and scenarios.
 
+
+DBAPI, HTTP, and BLOB interfaces
+================================
+
+The examples in this section are all about CrateDB's `Python DBAPI`_ interface,
+the plain HTTP API interface, and a convenience interface for working with
+`blob tables`_. It also details attributes, methods, and behaviors of the
+``Connection`` and ``Cursor`` objects.
+
 .. toctree::
  :maxdepth: 1
 
@@ -19,3 +28,25 @@ client, exercising different options and scenarios.
  blob
  connection
  cursor
+
+
+.. _sqlalchemy-by-example:
+
+SQLAlchemy interface
+====================
+
+The examples in this section are all about CrateDB's `SQLAlchemy`_ dialect, and
+its corresponding API interfaces, see also :ref:`sqlalchemy-support`.
+
+.. toctree::
+ :maxdepth: 1
+
+ sqlalchemy/getting-started
+ sqlalchemy/cru
+ sqlalchemy/inspection-reflection
+ sqlalchemy/internals
+
+
+.. _blob tables: https://crate.io/docs/crate/reference/en/latest/general/blobs.html
+.. _Python DBAPI: https://peps.python.org/pep-0249/
+.. _SQLAlchemy: https://www.sqlalchemy.org/

src/crate/client/sqlalchemy/doctests/itests.txt → docs/by-example/sqlalchemy/cru.rst

@@ -1,10 +1,30 @@
-==================
-SQLAlchemy Dialect
-==================
+========================================
+SQLAlchemy: Create, retrieve, and update
+========================================
+
+This section of the documentation, related to CrateDB's SQLAlchemy integration,
+focuses on showing specific details when querying, inserting, and updating
+records. It covers filtering and limiting, insert and update default values,
+and updating complex data types with nested Python dictionaries.
+
+.. rubric:: Table of Contents
+
+.. contents::
+ :local:
+
+
+Setup
+=====
+
+Establish a connection to the database:
 
  >>> connection = engine.connect()
 
-Using the connection to execute a select statement::
+
+Retrieve
+========
+
+Using the connection to execute a select statement:
 
  >>> result = connection.execute('select name from locations order by name')
  >>> result.rowcount
@@ -13,33 +33,36 @@ Using the connection to execute a select statement::
  >>> result.first()
  ('Aldebaran',)
 
-Using the ORM to query the locations::
+Using the ORM to query the locations:
 
  >>> locations = session.query(Location).order_by('name')
  >>> [l.name for l in locations if l is not None][:2]
  ['Aldebaran', 'Algol']
 
-With limit and offset::
+With limit and offset:
 
  >>> locations = session.query(Location).order_by('name').offset(1).limit(2)
  >>> [l.name for l in locations if l is not None]
  ['Algol', 'Allosimanius Syneca']
 
-With filter::
+With filter:
 
  >>> location = session.query(Location).filter_by(name='Algol').one()
  >>> location.name
  'Algol'
 
-Order by::
+Order by:
 
  >>> locations = session.query(Location).filter(Location.name != None).order_by(sa.desc(Location.name))
  >>> locations = locations.limit(2)
  >>> [l.name for l in locations]
  ['Outer Eastern Rim', 'North West Ripple']
 
 
-Insert a new location::
+Create
+======
+
+Insert a new location:
 
  >>> location = Location()
  >>> location.name = 'Earth'
@@ -53,19 +76,19 @@ Refresh "locations" table:
 
  >>> _ = connection.execute("REFRESH TABLE locations")
 
-Inserted location is available::
+Inserted location is available:
 
  >>> location = session.query(Location).filter_by(name='Earth').one()
  >>> location.name
  'Earth'
 
-Retrieve the location from the database::
+Retrieve the location from the database:
 
  >>> session.refresh(location)
  >>> location.name
  'Earth'
 
-Date should have been set at the insert due to default value via python method::
+Date should have been set at the insert due to default value via Python method:
 
  >>> from datetime import datetime
  >>> now = datetime.utcnow()
@@ -83,7 +106,7 @@ Date should have been set at the insert due to default value via python method::
  >>> (now - location.datetime_tz).seconds < 4
  True
 
-Verify the return type of date and datetime::
+Verify the return type of date and datetime:
 
  >>> type(location.date)
  <class 'datetime.date'>
@@ -94,16 +117,20 @@ Verify the return type of date and datetime::
  >>> type(location.datetime_notz)
  <class 'datetime.datetime'>
 
-the location also has a date and datetime property which both are nullable and
-aren't set when the row is inserted as there is no default method::
+The location also has a date and datetime property which both are nullable and
+aren't set when the row is inserted as there is no default method:
 
  >>> location.nullable_datetime is None
  True
 
  >>> location.nullable_date is None
  True
 
-The datetime and date can be set using a update statement::
+
+Update
+======
+
+The datetime and date can be set using a update statement:
 
  >>> location.nullable_date = datetime.utcnow().date()
  >>> location.nullable_datetime = datetime.utcnow()
@@ -113,30 +140,30 @@ Refresh "locations" table:
 
  >>> _ = connection.execute("REFRESH TABLE locations")
 
-Boolean values get set natively::
+Boolean values get set natively:
 
  >>> location.flag
  True
 
-Reload the object from the db::
+Reload the object from the db:
 
  >>> session.refresh(location)
 
-And verify that the date and datetime was persisted::
+And verify that the date and datetime was persisted:
 
  >>> location.nullable_datetime is not None
  True
 
  >>> location.nullable_date is not None
  True
 
-Update one Location via raw sql::
+Update a record using SQL:
 
  >>> result = connection.execute("update locations set kind='Heimat' where name='Earth'")
  >>> result.rowcount
  1
 
-Update multiple Locations::
+Update multiple records:
 
  >>> for x in range(10):
  ... loc = Location()
@@ -145,7 +172,7 @@ Update multiple Locations::
  ... session.add(loc)
  ... session.flush()
 
-Refresh "locations" table:
+Refresh table:
 
  >>> _ = connection.execute("REFRESH TABLE locations")
 
@@ -156,7 +183,7 @@ Query database:
  10
 
 Check that number of affected documents of update without ``where-clause`` matches number of all
-documents in the table::
+documents in the table:
 
  >>> result = connection.execute(u"update locations set kind='Überall'")
  >>> result.rowcount == connection.execute("select * from locations limit 100").rowcount
@@ -168,7 +195,7 @@ Refresh "locations" table:
 
  >>> _ = connection.execute("REFRESH TABLE locations")
 
-Test that objects can be used as list too::
+Test that objects can be used as list too:
 
  >>> location = session.query(Location).filter_by(name='Folfanga').one()
  >>> location.details = [{'size': 'huge'}, {'clima': 'cold'}]
@@ -179,7 +206,7 @@ Test that objects can be used as list too::
  >>> location.details
  [{'size': 'huge'}, {'clima': 'cold'}]
 
-Update the clima::
+Update the record:
 
  >>> location.details[1] = {'clima': 'hot'}
 
@@ -189,7 +216,7 @@ Update the clima::
  >>> location.details
  [{'size': 'huge'}, {'clima': 'hot'}]
 
-Reset the clima::
+Reset the record:
 
  >>> location.details = []
  >>> session.commit()
@@ -198,7 +225,7 @@ Reset the clima::
  >>> location.details
  []
 
-test updated nested dict::
+Update nested dictionary:
 
  >>> from crate.client.sqlalchemy.types import Craty
  >>> class Character(Base):