因为看着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