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

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)