From 88b50e9718939de9559cdb780213a1336a151e55 Mon Sep 17 00:00:00 2001 From: Andreas Motl Date: Tue, 20 Dec 2022 10:23:44 +0100 Subject: [PATCH] Documentation: Improve conciseness and wording of recently updated sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Mathias Fußenegger --- docs/by-example/connection.rst | 6 ++-- docs/by-example/cursor.rst | 5 ++-- docs/by-example/index.rst | 4 +-- docs/by-example/sqlalchemy/crud.rst | 12 ++++---- .../sqlalchemy/inspection-reflection.rst | 29 ++++++++++--------- 5 files changed, 29 insertions(+), 27 deletions(-) diff --git a/docs/by-example/connection.rst b/docs/by-example/connection.rst index 0410ce06..6aafb1f2 100644 --- a/docs/by-example/connection.rst +++ b/docs/by-example/connection.rst @@ -5,9 +5,9 @@ The Connection object This documentation section outlines different attributes, methods, and behaviors of the ``crate.client.connection.Connection`` object. -To improve focus and reduce boilerplate, the example code uses an instance of -``ClientMocked`` instead of a real ``Client`` instance. It is used for -demonstration purposes, so the example doesn't need a real database connection. +The examples use an instance of ``ClientMocked`` instead of a real ``Client`` +instance. This allows us to verify the examples without needing a real database +connection. .. rubric:: Table of Contents diff --git a/docs/by-example/cursor.rst b/docs/by-example/cursor.rst index 3cf624be..0b979f4d 100644 --- a/docs/by-example/cursor.rst +++ b/docs/by-example/cursor.rst @@ -5,9 +5,8 @@ The Cursor object This documentation section outlines different attributes, methods, and behaviors of the ``crate.client.cursor.Cursor`` object. -To improve focus and reduce boilerplate, the example code uses both -``ClientMocked`` and ``set_next_response``. They are required for demonstration -purposes, so the example does not need a real database connection. +The example code uses ``ClientMocked`` and ``set_next_response`` for +demonstration purposes, so they don't need a real database connection. .. rubric:: Table of Contents diff --git a/docs/by-example/index.rst b/docs/by-example/index.rst index 54afc42b..3e7dfdec 100644 --- a/docs/by-example/index.rst +++ b/docs/by-example/index.rst @@ -8,7 +8,7 @@ About ***** This part of the documentation contains examples how to use the CrateDB Python -client, exercising different options and scenarios. +client. DBAPI, HTTP, and BLOB interfaces @@ -16,7 +16,7 @@ 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 +`blob tables`_. It details attributes, methods, and behaviors of the ``Connection`` and ``Cursor`` objects. .. toctree:: diff --git a/docs/by-example/sqlalchemy/crud.rst b/docs/by-example/sqlalchemy/crud.rst index 30e4a8f5..fbdf94c5 100644 --- a/docs/by-example/sqlalchemy/crud.rst +++ b/docs/by-example/sqlalchemy/crud.rst @@ -2,12 +2,14 @@ SQLAlchemy: Create, retrieve, update, and delete ================================================ -This section of the documentation, related to CrateDB's SQLAlchemy integration, -focuses on showing specific details when querying, inserting, updating, and -deleting records. +This section of the documentation shows how to query, insert, update and delete +data using CrateDB's SQLAlchemy integration, it includes common scenarios like: -It exercises filtering and limiting, inserting and updating with default values, -and updating complex data types with nested Python dictionaries. + +- Filtering records +- Limiting result sets +- Inserts and updates with default values +- Updating complex data types with nested dictionaries .. rubric:: Table of Contents diff --git a/docs/by-example/sqlalchemy/inspection-reflection.rst b/docs/by-example/sqlalchemy/inspection-reflection.rst index 27b0905e..6151c71d 100644 --- a/docs/by-example/sqlalchemy/inspection-reflection.rst +++ b/docs/by-example/sqlalchemy/inspection-reflection.rst @@ -2,23 +2,23 @@ SQLAlchemy: Database schema inspection and reflection ===================================================== -This section of the documentation, related to CrateDB's SQLAlchemy integration, -focuses on database schema inspection and reflection features. That is, given -that you connect to an existing database, how to introspect its metadata -information to retrieve table- and view-names, and table column metadata. +This section shows you how to inspect the schema of a database using CrateDB's +SQLAlchemy integration. Introduction ============ -The `runtime inspection API`_ provides the ``inspect()`` function, which -delivers runtime information about a wide variety of SQLAlchemy objects, both -within SQLAlchemy Core and the SQLAlchemy ORM. -The ``CrateDialect`` instance provides metadata about the CrateDB cluster, -like version and schema information. +The CrateDB SQLAlchemy integration provides different ways to inspect the database. -As always, let's start with creating an ``Engine`` instance. +1) The `runtime inspection API`_ allows you to get an ``Inspector`` instance that can be used to fetch schema names, table names and other information. + +2) Reflection capabilities allow you to create ``Table`` instances from existing tables to inspect their columns and constraints. + +3) A ``CrateDialect`` allows you to get connection information and it contains low level function to check the existence of schemas and tables. + +All approaches require an ``Engine`` instance, which you can create like this: >>> import sqlalchemy as sa >>> engine = sa.create_engine(f"crate://{crate_host}") @@ -29,7 +29,8 @@ Inspector The `SQLAlchemy inspector`_ is a low level interface which provides a backend-agnostic system of loading lists of schema, table, column, and -constraint descriptions from a given database. +constraint descriptions from a given database. You create an inspector like +this: >>> inspector = sa.inspect(engine) @@ -60,9 +61,9 @@ Get default schema name: Schema-supported reflection =========================== -A ``Table`` object can be instructed to load information about itself from the -corresponding database schema object already existing within the database. This -process is called *reflection*, see `reflecting database objects`_. +A ``Table`` object can load its own schema information from the corresponding +table in the database. This process is called *reflection*, see `reflecting +database objects`_. In the most simple case you need only specify the table name, a ``MetaData`` object, and the ``autoload_with`` argument.