codekingpro/portable-devtools

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