From 013ddd6b2e084a1adadca953ef695a6f90d0769d Mon Sep 17 00:00:00 2001 From: David Lord Date: Fri, 7 Jun 2024 17:08:15 -0700 Subject: [PATCH] fix api links --- docs/engine.md | 6 +++--- docs/session.md | 15 ++++++++------- docs/start.md | 9 +++++---- 3 files changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/engine.md b/docs/engine.md index c3cc399..d15b92b 100644 --- a/docs/engine.md +++ b/docs/engine.md @@ -97,8 +97,8 @@ The connection charset is set to `utf8mb4`. ## The Default Engine and Bind -The `"default"` key is special, and will be used for {attr}`.SQLAlchemy.engine` -and as the default bind for {attr}`.SQLAlchemy.sessionmaker`. By default, it is +The `"default"` key is special, and will be used for {attr}`~.SQLAlchemy.engine` +and as the default bind for {attr}`~.SQLAlchemy.sessionmaker`. By default, it is an error not to configure it for one of sync or async engines. @@ -107,7 +107,7 @@ an error not to configure it for one of sync or async engines. You can ignore the Flask config altogether and create engines yourself. In that case, you pass `require_default_engine=False` when creating the extension to ignore the check for default config. Adding custom engines to the -{attr}`.SQLAlchemy.engines` map will make them accessible through the extension, +{attr}`~.SQLAlchemy.engines` map will make them accessible through the extension, but that's not required either. You will want to call `db.sessionmaker.configure(bind=..., binds=...)` to set up these custom engines if you plan to use the provided session management though. diff --git a/docs/session.md b/docs/session.md index 5f76677..8043b4e 100644 --- a/docs/session.md +++ b/docs/session.md @@ -16,13 +16,13 @@ different options for each. ## Session Management Most use cases will use one session, and tie it to the lifetime of each request. -Use {attr}`db.session ` for this. It will return the same +Use {attr}`db.session <.SQLAlchemy.session>` for this. It will return the same session throughout a request, then close it when the request ends. SQLAlchemy will rollback any uncomitted state in the session when it is closed. You can also create other sessions besides the default. Calling -{meth}`db.get_session(name)` will create separate sessions that are also closed -at the end of the request. +{meth}`db.get_session(name) <.SQLAlchemy.get_session>` will create separate +sessions that are also closed at the end of the request. The sessions are closed when the application context is torn down. This happens for each request, but also at the end of CLI commands, and for manual @@ -31,7 +31,7 @@ for each request, but also at the end of CLI commands, and for manual ### Manual Sessions -You can also use {attr}`db.sessionmaker ` directly to +You can also use {attr}`db.sessionmaker <.SQLAlchemy.sessionmaker>` directly to create sessions. These will not be closed automatically at the end of requests, so you'll need to manage them manually. An easy way to do that is using a `with` block. @@ -47,9 +47,10 @@ with db.sessionmaker() as session: SQLAlchemy warns that the async sessions it provides are _not_ safe to be used across concurrent tasks. For example, the same session should not be passed to multiple tasks when using `asyncio.gather`. Either use -{meth}`db.get_async_session(name) ` with a unique -name for each task, or use {attr}`db.async_sessionmaker` to manage sessions -and their lifetime manually. The latter is what SQLAlchemy recommends. +{meth}`db.get_async_session(name) <.SQLAlchemy.get_async_session>` with a unique +name for each task, or use +{attr}`db.async_sessionmaker <.SQLAlchemy.async_sessionmaker>` to manage session +lifetimes manually. The latter is what SQLAlchemy recommends. ## Multiple Binds diff --git a/docs/start.md b/docs/start.md index d83a5a1..31afb36 100644 --- a/docs/start.md +++ b/docs/start.md @@ -15,7 +15,7 @@ SQLAlchemy. Create an instance of {class}`.SQLAlchemy`. Define the {data}`.SQLALCHEMY_ENGINES` config, a dict, with at least the `"default"` key with a [connection string] value. When setting up the Flask app, call the -extension's {meth}`.SQLAlchemy.init_app` method. +extension's {meth}`~.SQLAlchemy.init_app` method. [connection string]: https://docs.sqlalchemy.org/core/engines.html#database-urls @@ -200,6 +200,7 @@ be aware of than with sync usage. In particular, SQLAlchemy warns that the async sessions it provides are _not_ safe to be used across concurrent tasks. For example, the same session should not be passed to multiple tasks when using `asyncio.gather`. Either use -{meth}`db.get_async_session(name) ` with a unique -name for each task, or use {attr}`db.async_sessionmaker` to manage sessions -and their lifetime manually. The latter is what SQLAlchemy recommends. +{meth}`db.get_async_session(name) <.SQLAlchemy.get_async_session>` with a unique +name for each task, or use +{attr}`db.async_sessionmaker <.SQLAlchemy.async_sessionmaker>` to manage session +lifetimes manually. The latter is what SQLAlchemy recommends.