From 91d3932221a13756c6cead5f3e8ad734162639d3 Mon Sep 17 00:00:00 2001 From: Frank Yu Date: Mon, 15 Jan 2024 05:38:05 +0800 Subject: [PATCH 01/20] refactor docs (#1301) --- README.rst | 4 ++-- docs/customizing.rst | 29 ++++++++++++++--------------- docs/models.rst | 6 +++--- docs/pagination.rst | 2 +- docs/quickstart.rst | 6 +++--- 5 files changed, 23 insertions(+), 24 deletions(-) diff --git a/README.rst b/README.rst index 92e3b29e..fb4b4a15 100644 --- a/README.rst +++ b/README.rst @@ -40,8 +40,8 @@ A Simple Example db = SQLAlchemy(app, model_class=Base) class User(db.Model): - id: Mapped[int] = mapped_column(db.Integer, primary_key=True) - username: Mapped[str] = mapped_column(db.String, unique=True, nullable=False) + id: Mapped[int] = mapped_column(primary_key=True) + username: Mapped[str] = mapped_column(unique=True) with app.app_context(): db.create_all() diff --git a/docs/customizing.rst b/docs/customizing.rst index 05ab71db..8c8c5abb 100644 --- a/docs/customizing.rst +++ b/docs/customizing.rst @@ -37,10 +37,10 @@ joined-table inheritance. db = SQLAlchemy(app, model_class=Base) class User(db.Model): - name: Mapped[str] = mapped_column(String) + name: Mapped[str] class Employee(User): - title: Mapped[str] = mapped_column(String) + title: Mapped[str] Abstract Models and Mixins @@ -52,34 +52,33 @@ they are created or updated. .. code-block:: python - from datetime import datetime - from sqlalchemy import DateTime, Integer, String - from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, declared_attr + from datetime import datetime, timezone + from sqlalchemy.orm import Mapped, mapped_column class TimestampModel(db.Model): __abstract__ = True - created: Mapped[datetime] = mapped_column(DateTime, nullable=False, default=datetime.utcnow) - updated: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow) + created: Mapped[datetime] = mapped_column(default=lambda: datetime.now(timezone.utc)) + updated: Mapped[datetime] = mapped_column(default=lambda: datetime.now(timezone.utc), onupdate=lambda: datetime.now(timezone.utc)) class Author(db.Model): - id: Mapped[int] = mapped_column(Integer, primary_key=True) - username: Mapped[str] = mapped_column(String, unique=True, nullable=False) + id: Mapped[int] = mapped_column(primary_key=True) + username: Mapped[str] = mapped_column(unique=True) class Post(TimestampModel): - id: Mapped[int] = mapped_column(Integer, primary_key=True) - title: Mapped[str] = mapped_column(String, nullable=False) + id: Mapped[int] = mapped_column(primary_key=True) + title: Mapped[str] This can also be done with a mixin class, inheriting from ``db.Model`` separately. .. code-block:: python class TimestampMixin: - created: Mapped[datetime] = mapped_column(DateTime, nullable=False, default=datetime.utcnow) - updated: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow) + created: Mapped[datetime] = mapped_column(default=lambda: datetime.now(timezone.utc)) + updated: Mapped[datetime] = mapped_column(default=lambda: datetime.now(timezone.utc), onupdate=lambda: datetime.now(timezone.utc)) class Post(TimestampMixin, db.Model): - id: Mapped[int] = mapped_column(Integer, primary_key=True) - title: Mapped[str] = mapped_column(String, nullable=False) + id: Mapped[int] = mapped_column(primary_key=True) + title: Mapped[str] Disabling Table Name Generation diff --git a/docs/models.rst b/docs/models.rst index f2c6a159..6a471351 100644 --- a/docs/models.rst +++ b/docs/models.rst @@ -86,9 +86,9 @@ is not set and a primary key column is defined. from sqlalchemy.orm import Mapped, mapped_column class User(db.Model): - id: Mapped[int] = mapped_column(db.Integer, primary_key=True) - username: Mapped[str] = mapped_column(db.String, unique=True, nullable=False) - email: Mapped[str] = mapped_column(db.String) + id: Mapped[int] = mapped_column(primary_key=True) + username: Mapped[str] = mapped_column(unique=True) + email: Mapped[str] Defining a model does not create it in the database. Use :meth:`~.SQLAlchemy.create_all` diff --git a/docs/pagination.rst b/docs/pagination.rst index 8db2f22c..8289fdf5 100644 --- a/docs/pagination.rst +++ b/docs/pagination.rst @@ -58,7 +58,7 @@ The following Jinja macro renders a simple pagination widget. .. code-block:: jinja {% macro render_pagination(pagination, endpoint) %} -
+
{{ pagination.first }} - {{ pagination.last }} of {{ pagination.total }}