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

1# sql/roles.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 

7from __future__ import annotations 

8 

9from typing import Any 

10from typing import Generic 

11from typing import Optional 

12from typing import TYPE_CHECKING 

13from typing import TypeVar 

14 

15from .. import util 

16from ..util.typing import Literal 

17 

18if TYPE_CHECKING: 

19 from ._typing import _PropagateAttrsType 

20 from .elements import Label 

21 from .selectable import _SelectIterable 

22 from .selectable import FromClause 

23 from .selectable import Subquery 

24 

25_T = TypeVar("_T", bound=Any) 

26_T_co = TypeVar("_T_co", bound=Any, covariant=True) 

27 

28 

29class SQLRole: 

30 """Define a "role" within a SQL statement structure. 

31 

32 Classes within SQL Core participate within SQLRole hierarchies in order 

33 to more accurately indicate where they may be used within SQL statements 

34 of all types. 

35 

36 .. versionadded:: 1.4 

37 

38 """ 

39 

40 __slots__ = () 

41 allows_lambda = False 

42 uses_inspection = False 

43 

44 

45class UsesInspection: 

46 __slots__ = () 

47 _post_inspect: Literal[None] = None 

48 uses_inspection = True 

49 

50 

51class AllowsLambdaRole: 

52 __slots__ = () 

53 allows_lambda = True 

54 

55 

56class HasCacheKeyRole(SQLRole): 

57 __slots__ = () 

58 _role_name = "Cacheable Core or ORM object" 

59 

60 

61class ExecutableOptionRole(SQLRole): 

62 __slots__ = () 

63 _role_name = "ExecutionOption Core or ORM object" 

64 

65 

66class LiteralValueRole(SQLRole): 

67 __slots__ = () 

68 _role_name = "Literal Python value" 

69 

70 

71class ColumnArgumentRole(SQLRole): 

72 __slots__ = () 

73 _role_name = "Column expression" 

74 

75 

76class ColumnArgumentOrKeyRole(ColumnArgumentRole): 

77 __slots__ = () 

78 _role_name = "Column expression or string key" 

79 

80 

81class StrAsPlainColumnRole(ColumnArgumentRole): 

82 __slots__ = () 

83 _role_name = "Column expression or string key" 

84 

85 

86class ColumnListRole(SQLRole): 

87 """Elements suitable for forming comma separated lists of expressions.""" 

88 

89 __slots__ = () 

90 

91 

92class StringRole(SQLRole): 

93 """mixin indicating a role that results in strings""" 

94 

95 __slots__ = () 

96 

97 

98class TruncatedLabelRole(StringRole, SQLRole): 

99 __slots__ = () 

100 _role_name = "String SQL identifier" 

101 

102 

103class ColumnsClauseRole(AllowsLambdaRole, UsesInspection, ColumnListRole): 

104 __slots__ = () 

105 _role_name = ( 

106 "Column expression, FROM clause, or other columns clause element" 

107 ) 

108 

109 @property 

110 def _select_iterable(self) -> _SelectIterable: 

111 raise NotImplementedError() 

112 

113 

114class TypedColumnsClauseRole(Generic[_T_co], SQLRole): 

115 """element-typed form of ColumnsClauseRole""" 

116 

117 __slots__ = () 

118 

119 

120class LimitOffsetRole(SQLRole): 

121 __slots__ = () 

122 _role_name = "LIMIT / OFFSET expression" 

123 

124 

125class ByOfRole(ColumnListRole): 

126 __slots__ = () 

127 _role_name = "GROUP BY / OF / etc. expression" 

128 

129 

130class GroupByRole(AllowsLambdaRole, UsesInspection, ByOfRole): 

131 __slots__ = () 

132 # note there's a special case right now where you can pass a whole 

133 # ORM entity to group_by() and it splits out. we may not want to keep 

134 # this around 

135 

136 _role_name = "GROUP BY expression" 

137 

138 

139class OrderByRole(AllowsLambdaRole, ByOfRole): 

140 __slots__ = () 

141 _role_name = "ORDER BY expression" 

142 

143 

144class StructuralRole(SQLRole): 

145 __slots__ = () 

146 

147 

148class StatementOptionRole(StructuralRole): 

149 __slots__ = () 

150 _role_name = "statement sub-expression element" 

151 

152 

153class OnClauseRole(AllowsLambdaRole, StructuralRole): 

154 __slots__ = () 

155 _role_name = ( 

156 "ON clause, typically a SQL expression or " 

157 "ORM relationship attribute" 

158 ) 

159 

160 

161class WhereHavingRole(OnClauseRole): 

162 __slots__ = () 

163 _role_name = "SQL expression for WHERE/HAVING role" 

164 

165 

166class ExpressionElementRole(TypedColumnsClauseRole[_T_co]): 

167 # note when using generics for ExpressionElementRole, 

168 # the generic type needs to be in 

169 # sqlalchemy.sql.coercions._impl_lookup mapping also. 

170 # these are set up for basic types like int, bool, str, float 

171 # right now 

172 

173 __slots__ = () 

174 _role_name = "SQL expression element" 

175 

176 def label(self, name: Optional[str]) -> Label[_T]: 

177 raise NotImplementedError() 

178 

179 

180class ConstExprRole(ExpressionElementRole[_T]): 

181 __slots__ = () 

182 _role_name = "Constant True/False/None expression" 

183 

184 

185class LabeledColumnExprRole(ExpressionElementRole[_T]): 

186 __slots__ = () 

187 

188 

189class BinaryElementRole(ExpressionElementRole[_T]): 

190 __slots__ = () 

191 _role_name = "SQL expression element or literal value" 

192 

193 

194class InElementRole(SQLRole): 

195 __slots__ = () 

196 _role_name = ( 

197 "IN expression list, SELECT construct, or bound parameter object" 

198 ) 

199 

200 

201class JoinTargetRole(AllowsLambdaRole, UsesInspection, StructuralRole): 

202 __slots__ = () 

203 _role_name = ( 

204 "Join target, typically a FROM expression, or ORM " 

205 "relationship attribute" 

206 ) 

207 

208 

209class FromClauseRole(ColumnsClauseRole, JoinTargetRole): 

210 __slots__ = () 

211 _role_name = "FROM expression, such as a Table or alias() object" 

212 

213 _is_subquery = False 

214 

215 named_with_column: bool 

216 

217 

218class StrictFromClauseRole(FromClauseRole): 

219 __slots__ = () 

220 # does not allow text() or select() objects 

221 

222 

223class AnonymizedFromClauseRole(StrictFromClauseRole): 

224 __slots__ = () 

225 

226 if TYPE_CHECKING: 

227 

228 def _anonymous_fromclause( 

229 self, *, name: Optional[str] = None, flat: bool = False 

230 ) -> FromClause: ... 

231 

232 

233class ReturnsRowsRole(SQLRole): 

234 __slots__ = () 

235 _role_name = ( 

236 "Row returning expression such as a SELECT, a FROM clause, or an " 

237 "INSERT/UPDATE/DELETE with RETURNING" 

238 ) 

239 

240 

241class StatementRole(SQLRole): 

242 __slots__ = () 

243 _role_name = "Executable SQL or text() construct" 

244 

245 if TYPE_CHECKING: 

246 

247 @util.memoized_property 

248 def _propagate_attrs(self) -> _PropagateAttrsType: ... 

249 

250 else: 

251 _propagate_attrs = util.EMPTY_DICT 

252 

253 

254class SelectStatementRole(StatementRole, ReturnsRowsRole): 

255 __slots__ = () 

256 _role_name = "SELECT construct or equivalent text() construct" 

257 

258 def subquery(self) -> Subquery: 

259 raise NotImplementedError( 

260 "All SelectStatementRole objects should implement a " 

261 ".subquery() method." 

262 ) 

263 

264 

265class HasCTERole(ReturnsRowsRole): 

266 __slots__ = () 

267 

268 

269class IsCTERole(SQLRole): 

270 __slots__ = () 

271 _role_name = "CTE object" 

272 

273 

274class CompoundElementRole(AllowsLambdaRole, SQLRole): 

275 """SELECT statements inside a CompoundSelect, e.g. UNION, EXTRACT, etc.""" 

276 

277 __slots__ = () 

278 _role_name = ( 

279 "SELECT construct for inclusion in a UNION or other set construct" 

280 ) 

281 

282 

283# TODO: are we using this? 

284class DMLRole(StatementRole): 

285 __slots__ = () 

286 

287 

288class DMLTableRole(FromClauseRole): 

289 __slots__ = () 

290 _role_name = "subject table for an INSERT, UPDATE or DELETE" 

291 

292 

293class DMLColumnRole(SQLRole): 

294 __slots__ = () 

295 _role_name = "SET/VALUES column expression or string key" 

296 

297 

298class DMLSelectRole(SQLRole): 

299 """A SELECT statement embedded in DML, typically INSERT from SELECT""" 

300 

301 __slots__ = () 

302 _role_name = "SELECT statement or equivalent textual object" 

303 

304 

305class DDLRole(StatementRole): 

306 __slots__ = () 

307 

308 

309class DDLExpressionRole(StructuralRole): 

310 __slots__ = () 

311 _role_name = "SQL expression element for DDL constraint" 

312 

313 

314class DDLConstraintColumnRole(SQLRole): 

315 __slots__ = () 

316 _role_name = "String column name or column expression for DDL constraint" 

317 

318 

319class DDLReferredColumnRole(DDLConstraintColumnRole): 

320 __slots__ = () 

321 _role_name = ( 

322 "String column name or Column object for DDL foreign key constraint" 

323 )