codekingpro/portable-devtools

1# sql/_dml_constructors.py
2# Copyright (C) 2005-2026 the SQLAlchemy authors and contributors
3# <see AUTHORS file>
4#
5# This module is part of SQLAlchemy and is released under
6# the MIT License: https://www.opensource.org/licenses/mit-license.php
7
8from __future__ import annotations
9
10from typing import TYPE_CHECKING
11
12from .dml import Delete
13from .dml import Insert
14from .dml import Update
15
16if TYPE_CHECKING:
17    from ._typing import _DMLTableArgument
18
19
20def insert(table: _DMLTableArgument) -> Insert:
21    """Construct an :class:`_expression.Insert` object.
22
23    E.g.::
24
25        from sqlalchemy import insert
26
27        stmt = insert(user_table).values(name="username", fullname="Full Username")
28
29    Similar functionality is available via the
30    :meth:`_expression.TableClause.insert` method on
31    :class:`_schema.Table`.
32
33    .. seealso::
34
35        :ref:`tutorial_core_insert` - in the :ref:`unified_tutorial`
36
37
38    :param table: :class:`_expression.TableClause`
39     which is the subject of the
40     insert.
41
42    :param values: collection of values to be inserted; see
43     :meth:`_expression.Insert.values`
44     for a description of allowed formats here.
45     Can be omitted entirely; a :class:`_expression.Insert` construct
46     will also dynamically render the VALUES clause at execution time
47     based on the parameters passed to :meth:`_engine.Connection.execute`.
48
49    :param inline: if True, no attempt will be made to retrieve the
50     SQL-generated default values to be provided within the statement;
51     in particular,
52     this allows SQL expressions to be rendered 'inline' within the
53     statement without the need to pre-execute them beforehand; for
54     backends that support "returning", this turns off the "implicit
55     returning" feature for the statement.
56
57    If both :paramref:`_expression.insert.values` and compile-time bind
58    parameters are present, the compile-time bind parameters override the
59    information specified within :paramref:`_expression.insert.values` on a
60    per-key basis.
61
62    The keys within :paramref:`_expression.Insert.values` can be either
63    :class:`~sqlalchemy.schema.Column` objects or their string
64    identifiers. Each key may reference one of:
65
66    * a literal data value (i.e. string, number, etc.);
67    * a Column object;
68    * a SELECT statement.
69
70    If a ``SELECT`` statement is specified which references this
71    ``INSERT`` statement's table, the statement will be correlated
72    against the ``INSERT`` statement.
73
74    .. seealso::
75
76        :ref:`tutorial_core_insert` - in the :ref:`unified_tutorial`
77
78    """  # noqa: E501
79    return Insert(table)
80
81
82def update(table: _DMLTableArgument) -> Update:
83    r"""Construct an :class:`_expression.Update` object.
84
85    E.g.::
86
87        from sqlalchemy import update
88
89        stmt = (
90            update(user_table).where(user_table.c.id == 5).values(name="user #5")
91        )
92
93    Similar functionality is available via the
94    :meth:`_expression.TableClause.update` method on
95    :class:`_schema.Table`.
96
97    :param table: A :class:`_schema.Table`
98     object representing the database
99     table to be updated.
100
101
102    .. seealso::
103
104        :ref:`tutorial_core_update_delete` - in the :ref:`unified_tutorial`
105
106
107    """  # noqa: E501
108    return Update(table)
109
110
111def delete(table: _DMLTableArgument) -> Delete:
112    r"""Construct :class:`_expression.Delete` object.
113
114    E.g.::
115
116        from sqlalchemy import delete
117
118        stmt = delete(user_table).where(user_table.c.id == 5)
119
120    Similar functionality is available via the
121    :meth:`_expression.TableClause.delete` method on
122    :class:`_schema.Table`.
123
124    :param table: The table to delete rows from.
125
126    .. seealso::
127
128        :ref:`tutorial_core_update_delete` - in the :ref:`unified_tutorial`
129
130
131    """
132    return Delete(table)
133