Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/sqlalchemy/sql/_dml_constructors.py: 64%

1# sql/_dml_constructors.py 

2# Copyright (C) 2005-2025 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)