“文档”略谈，从SQLAlchemy开始

因为看着SQLAlchemy的文档，被其动态变化的目录以及繁冗的结构、内容所困扰，所以进行此番整理，主要想阐明整体结构：

——文档是创作者和学习者之间一个非常苦逼的矛盾，我感到这方面做的最好的非Python的龟叔莫属。他在整体结构、具体行文和示例使用上，都能直达Python精髓。文档读起来倍感赏心悦目，甚至可称作“美文”。
——而做的不好的太多了，比如这个SQLAlchemy文档足够让人迷路，另外还有MySQL文档，它居然有8000多页，你经常能在一页上看到二三十处“具体请见yyy页”、“这一点在xxx页会谈到”。。。
——我本人也是做的不好的，我曾经创作过ExcelSpice这个作品，它简化用VBA进行数据整理、统计的难度。然而文档，我表示非常抱歉，我的确写了很多自鸣得意的内容，其实它们对读者无益。其中也有一些“具体请见xxx”，因为我是用LaTex写的，觉得一些地方“真”需要标签链接，如果不用标签链接也对不起LaTex。实际上对于想快速掌握一个工具的读者来说，“具体请见xxx”是大麻烦，因为刚刚读完一段话，看到这个觉得白读了，如果真的跳到xxx页，又会中断当前思路，之后还得跳回来：在跳回来之前如果再遇到“请见yyy页”，甚至就跳不回来了。以后有时间，我一定会对第二版的文档进行大幅删减，删到一字不可再删为止。

 具体地址为：https://docs.sqlalchemy.org/en/14/intro.html，迷路了之后回到这里即可：

Overview

Documentation Overview
Code Examples
Installation Guide

Supported Platforms
AsyncIO Support
Supported Installation Methods
Install via pip
Installing using setup.py
Installing the C Extensions
Installing a Database API
Checking the Installed SQLAlchemy Version

1.3 to 1.4 Migration

SQLAlchemy 1.4 / 2.0 Tutorial

Tutorial Overview

Version Check
A Note on the Future

Establishing Connectivity - the Engine
Working with Transactions and the DBAPI
Working with Database Metadata
Working with Data
Data Manipulation with the ORM
Working with Related Objects
Further Reading

SQLAlchemy ORM
（到这一章，突然非常正式排版出一个目录页，内容和之前的ORM也不一样，让我觉得之前看到的ORM是不是都是寂寞：细思起来，这里的第一部分是将要废弃的1.x版本，然而即便其他的部分也似乎也之前的ORM in Tutorial没有关系）

Object Relational Tutorial (1.x API)

Version Check
Connecting
Declare a Mapping
Create a Schema
Create an Instance of the Mapped Class
Creating a Session
Adding and Updating Objects
Rolling Back
Querying
Building a Relationship
Working with Related Objects
Querying with Joins
Eager Loading
Deleting
Building a Many To Many Relationship
Further Reference

Mapper Configuration

Mapping Python Classes
Mapping Classes with Declarative
Mapping Columns and Expressions
Mapping Class Inheritance Hierarchies
Non-Traditional Mappings
Configuring a Version Counter
Class Mapping API

Relationship Configuration

Basic Relationship Patterns
Late-Evaluation of Relationship Arguments
Adjacency List Relationships
Linking Relationships with Backref
Configuring how Relationship Joins
Collection Configuration and Techniques
Special Relationship Persistence Patterns
Relationships API

Querying Data, Loading Objects

ORM Querying Guide
Loading Columns
Relationship Loading Techniques
Loading Inheritance Hierarchies
Constructors and Object Initialization
Query API

Using the Session

Session Basics
State Management
Cascades
Transactions and Connection Management
Additional Persistence Techniques
Contextual/Thread-local Sessions
Tracking queries, object and Session Changes with Events
Session API

Events and Internals

ORM Events
ORM Internals
ORM Exceptions

ORM Extensions

Asynchronous I/O (asyncio)
Association Proxy
Automap
Baked Queries
Declarative Extensions
Mypy / Pep-484 Support for ORM Mappings
Mutation Tracking
Ordering List
Horizontal Sharding
Hybrid Attributes
Indexable
Alternate Class Instrumentation

ORM Examples

Mapping Recipes
Inheritance Mapping Recipes
Special APIs
Extending the ORM

SQLAlchemy Core

（这一章，也有正式的目录页）

SQL Expression Language Tutorial (1.x API)

Version Check
Connecting
Define and Create Tables
Insert Expressions
Executing
Executing Multiple Statements
Selecting
Selecting Specific Columns
Operators
Conjunctions
Using Textual SQL
Using Aliases and Subqueries
Using Joins
Common Table Expressions (CTE)
Everything Else
Inserts, Updates and Deletes
Further Reference

SQL Statements and Expressions API

Column Elements and Expressions
Operator Reference
Selectables, Tables, FROM objects
Insert, Updates, Deletes
SQL and Generic Functions
Custom SQL Constructs and Compilation Extension
Expression Serializer Extension
Visitor and Traversal Utilities

Schema Definition Language

Describing Databases with MetaData
Reflecting Database Objects
Column INSERT/UPDATE Defaults
Defining Constraints and Indexes
Customizing DDL

Column and Data Types

Column and Data Types
Custom Types
Base Type API

Engine and Connection Use

Engine Configuration
Working with Engines and Connections
Connection Pooling
Core Events

Core API Basics

Events
Runtime Inspection API
Core Exceptions
Core Internals

SQLAlchemy 2.0 Future (Core)

Dialects

Included Dialects

Support Levels for Included Dialects
Support Definitions

Deprecated, no longer supported dialects
External Dialects
PostgreSQL
MySQL and MariaDB
SQLite
Oracle
Microsoft SQL Server
Firebird
Sybase